This article is contributed. See the original author and article here.
Imagine you build an API only to realize later down the road, your documentation for it isn’t kept up to date and you are now spending more time trying to figure how it works than it took to build. Sound familiar? This is one of the common pitfalls of a code-first approach to APIs. There are two key approaches to building APIs:
- Code-first: coding the API directly from the requirements and then generating an API definition document
- Design-first: defining an API first and then implementing backend services based on the agreed API design
If you were to follow a design-first approach, you can design your API in API Management and export it to an OpenAPI specification file, which could be used to bring organizational alignment and serve as a guidance for implementing backend services that support the API logic and client applications that consume the API.
To support the design-first approach, we recently released an update to our Azure Functions and API Management Visual Studio Code extensions that lets you generate Azure Function apps by importing an OpenAPI specification. The same functionality is available via the command line.
Functions provide not only ready-made scaffolding for writing an API but all the necessary hosting.
Functions allow your API to dynamically scale up or down depending on the number of requests. Since it is consumption-based, you’re only charged when an HTTP endpoint is called, and you aren’t paying for idle resources as you would if you were using a VM as a host.
Imagine a scenario where you are creating an API for a food delivery service. After gathering the business requirements, you begin developing the API. Once the API is built, dependent teams start testing, documenting, and providing feedback. But while gathering feedback you realize you need to pivot and rewrite a significant portion of your API which is going to push back the project. That’s where the code-first approach falls short.
What if instead of developing the API, you started with an API description to establish a shared understanding of how the API is supposed to function. During the process of creating the description you start asking questions like: What functionality will the API have? What will the developer experience be like? What data will it expose and in what format? How will we add new functionality in the future? To answer some of these questions you need to bring in other teams to provide input. You can now get earlier validation on the API functionality from various stakeholders while the cost of making changes are low.
In addition to gathering feedback earlier in the API development process, teams that are consumers of the API can begin testing and integration before the business logic is complete. Dependent teams are not blocked by another team’s progress and can work in parallel during API development process.
Which approach should I use?
Determining what approach to use will depend on your business needs and use case. The code-first approach is a more traditional approach to building APIs, but the popularity of API definition formats has led to the growing support of the design-first methodology.
Design-first allows consumers to better understand of how to use your API and ensures consistency across APIs.
Key benefits of a design-first approach are:
- Accelerates API development by establishing key details in the design phase and allowing development teams to work in parallel
- Results in a transparent API documentation to stakeholders
- Let’s you focus on the API consumer experience and the business logic that the API fulfills, detaching it from the technical implementation
- Helps to create a strong foundation for the API, which may reduce the number of breaking changes in future
Building a REST API in three steps
In three easy steps you can design and build your API’s without writing a bunch of lines of code and documentation.
Step 1: Create an API definition using API Management
In API Management, choose API’s from the left menu, and then select OpenAPI.
In the Create from OpenAPI specification window, select Full. Fill in your API values in the necessary fields and select create. Here is a sample Open API file you can use.
Step 2: Generate function apps from Open API Specifications
Now that you have created an OpenAPI specification file you can import the specification via the API Management or Azure Functions VS Code extensions to create the scaffolding for your API.
Getting started with VS Code
Before you get started there’s a few things you will need:
- Visual Studio Code
- Latest version of the Azure Functions extension or API Management Extension
- AutoRest (Microsoft’s OpenAPI specification generator)
From API Management Extension
In your VS code settings make sure you enable the API Management extension to create Functions.
In the API management VS code extension right click on the API definition you would like to use and select scaffold Azure Functions.
Select your language of choice and where you would like to create the functions.
Watch as it starts to generate function apps from your specification file!
From Azure Functions Extension
You can also use the Azure Functions extension to import a specification to create the scaffolding for your API.
Create a new function app and choose your language of choice (TypeScript, Python, C#).
Select the HTTP trigger(s) from OpenAPI V2/V3 Specification template.
Select your OpenAPI specification file (You can find some samples to try here).
Step 3: Add your business logic
Once it completes you will see it has automatically generated all the necessary functions for your API, preconfigured based on the OpenAPI specification. All you need to do now is add your business logic to each function/route and deploy to Azure.
Getting started with CLI
You can also use the CLI as well to create the scaffolding for your API’s.
autorest --azure-functions-csharp --input-file:/path/to/spec.json --output-folder:./generated-azfunctions --version:3.0.6314 --namespace:Namespace
Check out the GitHub repo for more information on how to get started.
The design-first approach to building APIs comes with many benefits, saving you time and effort in bringing your APIs to market. Now you can reap the benefits even more by generating the Azure Functions scaffolding for your APIs from OpenAPI definition in Visual Studio Code. If you have an existing API hosted on Azure and you’re interested in exploring a serverless architecture or consumption-based billing model, this new capability is a fast track for getting started with Azure Functions.
To learn more about building serverless APIs with Azure Functions and Azure API Management, check out a new workshop we recently published on GitHub.
Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.