Alphadoc features: API Endpoints and variables

// Here there! My name is Daan and I'm one of the co-founders at Alphadoc. Follow me on LinkedIn where I post additional (hopefully) helpful content.

Roundup of Alphadoc features (1/4): API Endpoints and variables

The end of the year is coming up and we'd like to take some time and review what we deployed this year and also take the opportunity to dive a little bit deeper into some of the main features we released this year. This series of posts is showcasing some of the feature highlights of the past year we are particularly proud of.

Intro

To kick off the series we'll be reflecting on the first public release of the year, showcasing the features that developers and tech writers will find invaluable. At the heart of Alphadoc is a powerful component that allows you to create code examples combining real code, with real endpoints, with real variable data. API’s are the foundation of the platform. Our philosophy is that your API documentation should always be up-to-date with the latest versions of your specification, this includes tutorials, not just the specification. Using API endpoints reduces the cost of building great tutorials and enables you to build more use cases due to the modular nature of the platform.

The components that Alphadoc provides are great for building use cases on top of your OpenAPI specification. Combine them with variables to craft personal onboarding experiences. Endpoints can be added anywhere in Alphadoc, on any page (and even in other platforms!). They form the heart of Tutorials and are ultra flexible.

How do API endpoints work?

When an API is uploaded in Alphadoc we immediately display the entire spec in the API reference section. Each operation (like GET /user or POST /transaction) is displayed with all the information you and your integrating developers need. It includes a high degree of compliance with the OpenAPI specification and offers solutions for more complex use cases like using oneOfs and anyOfs* in your OAI specification. (scroll to the bottom for an explanation of what oneOfs and anyOfs are). 

Example code is generated on the spot, and you can customize it by overwriting any of the values. The endpoint component can be added to any page and after you do, you can completely customize it to make *that* use case for your customer. Combining the endpoint component with variables unlocks a new dimension in terms of customization. 

How do variables work?

To add a variable, just click on the variable icon above the sidebar. A drawer will slide out and you'll see which variables are available. To add a variable to an endpoint, click on the Add source button in any endpoint located on a page or tutorial.

Just like in programming, Alphadoc variables allow you to reuse information across multiple environments. Some variables come from the OpenAPI specification, and others can be declared by you, the editor of the content. Your readers can in-turn overwrite the values of each variable. For developers this is especially useful so you don't have to re-enter the same API key, account ID or organization name for every API call.

There are 3 different types of variables:

1. Project variables - These are declared by the editor and can optionally be overridden by the reader. This is useful for variables that are used for query, path or body parameters in API calls.

2. Server variables - In the spec you can define server variables that you defined in your spec. If you have an API (like we do!) that relies on the organization name being added to the subdomain (docs as in https://docs.alphadoc.io/v1) this can be set once and it will be automatically added everywhere.

3. Auth variables - For developers and integrators, the ability to set your authentication credentials just once and have them automatically apply across all API endpoints saves significant time and effort. This requires zero setup in Alphadoc, all you need to do is declare your auth method in the OpenAPI specification file and we'll take care of it when you upload. In each endpoint you'll still be able to overwrite the value if you want to test different things. As a security measure we remove the credentials once you close the browser tab.

Summary

In our latest blog post, we're excited to kick off a series that celebrates the innovative features we've rolled out this year, starting with the game-changing API endpoints and variables. These tools aren't just cool tech; they're the backbone of creating dynamic, real-world code examples that resonate with our users. We dive into how these API endpoints seamlessly align with the OpenAPI specification and how they can be customized with variables to fit your specific needs. This post marks the beginning of our exploration into this year's achievements. We invite you to join us in this journey and discover how Alphadoc's innovations can empower your development process.

*oneOfs and anyOfs

Imagine you're ordering a pizza and you have a menu with a bunch of different toppings. Now, think of "oneOfs" and "anyOfs" as special rules for how you can choose your toppings.

- "oneOf":This is like the pizza place saying, "Hey, we have these special combo pizzas with a bunch of different toppings. You can choose one, but only one of these topping combos." So, if there are combos like Pepperoni Fiesta, Veggie Delight, and Hawaiian Special, you can pick any one of these, but you can't mix toppings from different combos.

- "anyOf": This is more flexible. The pizza place says, "You can choose any toppings you like from this list. You can pick just one, or you can mix and match as many as you want!" So here, you could choose just cheese, or go wild with cheese, olives, chicken, and whatever else is on the list. Except for pineapple, you can't choose pineapple.