Runscope API Monitoring    Learn More →

Building Serverless Applications with an API-First Approach

By Mike Mackrory on .


Mike Mackrory a guest contributor for the Runscope blog. If you're interested in sharing your knowledge with our readers, please fill out this short form and we'll get in touch with you.

In this article, we’re going to be examining what an API-first design strategy looks like when it comes to developing serverless applications. We’re going to talk about why this approach is essential, what are its benefits, and walk through a simple example of creating a basic OpenAPI spec using SwaggerHub, and deploying it using AWS Lambda.

Start with the End in Mind

As developers and engineers, we like to solve problems. Give us an idea of what needs to be fixed or produced, and we’ll have our IDE open and our fingers tapping out magical code before you finish speaking.

Fast innovation is a good thing. In this case, however, there is a downside: You’ll end up with an API that is “designed” and “documented” as an afterthought and made to fit the code. This approach may require additional work to bring the vision of the product owner and the engineering team into alignment after a lot of work has been completed.

Your API should be a first-class citizen. Designing and documenting your API first allows stakeholders to weigh in on the design of the API; it will enable different parts of the organization to agree on consistent interactions with each other. API-first development forces the development team to think about the application in terms of user stories and real-life interactions. This approach allows for quick iteration to resolve potential problems before a line of code is written.

API-First Enables Parallel Development

When multiple teams are developing different components of a more extensive system, being able to create a part of the system based on an established and agreed-upon contract between services will save a great deal of time and headaches when the time comes for integration.

In an organization where each team has determined their API contracts before starting development, teams can mock out their dependencies, increasing the speed of development and minimizing later integration problems.

Why API-First Design is Especially Important for Serverless Applications

Honestly, everything we’ve talked about so far is a best practice for application development in general, not just serverless applications. Let’s look at a practical example of how to create a simple application using serverless technology. This application will allow us to create, retrieve and manage user preferences.

Before we get too far, let’s briefly define what "serverless" means to ensure we’re all starting from the same place. Serverless applications do run on servers, but developers don't need to think about the servers themselves, or any of the supporting infrastructure. Requiring no administrative input from the developer frees them up to focus purely on the application itself and meeting customer expectations. Examples of serverless providers are AWS Lambda, Azure Functions, and Google Cloud Functions.

Let’s follow API-first design principles and start with an API document to map out what we’re looking for specifically. We want to be able to create, update, retrieve and delete a user preference. Using the OpenAPI Specification, I put together a basic API contract on SwaggerHub.

The document defines what a Preference object looks like and describes each of the endpoints in detail. Shown below are examples of both the object definition and the GET-based endpoint.

   type: object
   - userId
   - preferenceName
   - status
       type: string
       format: uuid
       type: string
       type: string
       type: string
       description: Preference Status
       - test
       - enabled
       - disabled
       - deleted

     summary: Find preference by User ID
     description: Returns all user preferences
     operationId: getPreferenceByUserId
     - preference
     - application/json
     - name: userId
       in: path
       description: ID of user to return preferences for
       required: true
       type: string
       format: uuid
         description: successful operation
           $ref: '#/definitions/Preference'
         description: Invalid ID supplied
         description: User Preferences not found

Once the API contract is finalized, and all stakeholders have approved it, it is then up to the development team to implement it. The beauty of using an API contract for integration is that as long as the conventions are adhered to, the choice of language and other implementation details are mostly irrelevant, as long as they comply with the contract.

The API Contract—The Center Of Everything

As the primary interface between the development team and other teams, the API contract continues to support development efforts. Using a tool like CA Service Virtualization, other development teams can use the API document to create a virtual service and begin testing against a mocked version of the application before the code is complete.

Operations or production support teams can also begin to set up monitoring and performance tests with a tool such as Runscope. The OpenAPI-based document can be used to automatically generate tests to ensure the API is responding as expected, that the API is accessible for multiple regions, and that the API is responding in a performant way.

Finally, when development is complete, the API documentation can be used to connect the serverless application to the outside world through a service like AWS API Gateway.

Deployment and Management Made Easy with an API Contract

I used AWS Lambda to deploy my serverless applications for this project. The API document made it easy to establish connections between each of my serverless applications and the outside world with AWS API Gateway. All I needed to do was import the Swagger document into the API Gateway interface.

Creating a New API from Swagger Documentation

The next step after I imported the file was to connect each endpoint to the serverless/Lambda function created to support that endpoint, and my API was ready to be published and consumed.

Half the Work of Setting Up a New API Gateway is Done Automatically

Serverless applications allow you to take the concept of microservices and create a highly scalable ecosystem of loosely coupled functions. The API contracts which control this environment allow for incremental changes to be introduced without disrupting services which rely on the functions being enhanced. The API contracts also provide a way to manage this environment and enable teams to access those functions and APIs they need to support other development activities.

Categories: swagger, openapi, apis, serverless

Everything is going to be 200 OK®