Documenting APIs on Amazon API Gateway: Code-First or Design-First, The Choice Is Yours
One of the hardest debates is deciding between a code-first API approach or design-first. In an ideal world, we would deliver our APIs at maximum velocity, with minimum maintenance. To maintain the appropriate API consumption, the world has looked at Amazon’s API Gateway as the orchestration of resources to create, deploy, and manage APIs at scale.
One of the biggest challenges users face when using any API Gateway is the lack of consistency and standardization throughout the API experience. This is commonly seen in large organizations where there are multiple teams responsible for maintaining a complex API ecosystem. The result is an illogical and unpredictable API experience further impacting the consumption and adoption of the API.
To effectively manage an extensive API network, we need to start documenting the API, and documenting it correctly. Some API design tools, like SmartBear’s SwaggerHub, allow us to import the API into the tool and automatically parse the codebase to create the documentation. SwaggerHub has many more capabilities that enable developers to design, build, and document the API. With the help of the OpenAPI Specification (formerly known as Swagger), users can create custom rules to enforce all APIs to be set to the same standard.
Deciding between code-first or design-first is not always easy. The goal should be to get the APIs documented and standardized with maximum efficiency. Some projects will require code-first, and some will require design-first. Code-first is great for getting started quickly and building that application from the ground up. Since the documentation is generated from the code, it is very up to date. But there may be a lack of content or context in the documentation. Since it’s code-centric, it may not provide enough detail or be 100% correct. Design-first is known for having better clarity and guidance in the API documentation, therefore improving the collaboration and adoption of the API. Though the initial effort to document the API before implementation is not always worth it, there is a protentional for disconnect between the documentation and function, referred to as API drift.
The good thing is, there is no limitation of using one vs. the other. If done correctly, we expect a consistent API experience for all. Hosting on top of the most used gateway allows us to see in real time the API experience for end users and modify the experience if necessary.
Code-First with Amazon API Gateway and SwaggerHub
Now it is time to document the API. Our API is already hosted on an API Gateway. Go to the API we wish to standardize or document and publish the documentation (API must be deployed to publish documentation).
Figure 1 – Publish the API Documentation from Amazon API Gateway into Swagger YAML
Now let us import the API to SwaggerHub. Once the API is imported, it will automatically perform the standard Open API Specification validation, to make sure the API is correct, and any other custom rules are enabled.
Figure 2 – Import YAML into SwaggerHub
SwaggerHub has many other benefits that work hand in hand with any API Gateway. SwaggerHub Domains provides a centralized location for managing common components of APIs like schemas, security definitions, responses, and more. By using Domains, API developers can create and manage these components once and reuse them across multiple APIs, reducing duplicate work, ensuring consistent design, reducing errors, and producing rapid API development.
Figure 3 – Use SwaggerHub to Improve API Documentation
Amazon API Gateway and SwaggerHub both have command–line interfaces to help automate this integration, via a twostep pipeline. The perquisite is to download and configure the necessary command-line interfaces from AWS and SwaggerHub. In the first step of the pipeline, we Export a REST API from API Gateway using the AWS CLI. Next, using the SwaggerHub CLI we create the API in SwaggerHub. Once the API is within SwaggerHub, the API validations and custom guidelines automatically parse the API specification, to ensure a consistent API experience.
Figure 4 – Use SwaggerHub and API Gateway CLI to Integrate via Automation
Design-First with Amazon API Gateway and SwaggerHub
The design-first API methodology is implemented to help short-term velocity and long-term consistency. The consistency and standard that design-first carries are the main reasons most new APIs are created like this. The APIs are created with an API description language to help establish a contract for how the API is intended to behave.
First, the API is discussed with stakeholders to identify the key services and business function the API should create. We then design the API contract that would be in Open API Specification. Once that initial API specification is created, we can connect to the API Gateway. It does not matter what state the API itself is in; as we improve the API in SwaggerHub, changes and improvements of the API can be automatically pushed to the gateway. This generates the ability to test and develop in parallel, getting closer to shifting left.
SwaggerHub has two integrations that can help us immediately and automatically push the API to Amazon API Gateway. The SwaggerHub API Gateway Integration can be configured so every time you save the API in SwaggerHub, the Amazon API Gateway will automatically reflect that change by referencing the virtualized SwaggerHub API in a mock.
Figure 5 – The SwaggerHub API Gateway Integration once deployed
The other SwaggerHub Amazon API Gateway integration is the SwaggerHub Gateway Lambda Sync. The difference is the backend type you use. If you have an existing API server and you want to proxy or secure via Gateway, the SwaggerHub API Gateway Integration is the correct choice. The SwaggerHub Gateway Lambda Sync uses Lambda functions as the backend. Once the integration is configured in SwaggerHub, the API is automatically deployed to Amazon API Gateway.
Figure 6 – The SwaggerHub API Gateway Lambda Sync deployed
Once the Lambda functions are generated, we can take our API to the next level. We do this by injecting Python or Nodejs runtime engines on top of the API resource associated with the Lambda function to transition the API into a fully functioning application.
Figure 7 –The Lambda functions synced to SwaggerHub
Conclusion
There is no right or wrong for code-first or design-first. Both methodologies have their advantages and possibilities of misalignment. The best solution for API documentation is to document and document correctly. Whether teams prefer building the application code base first or developing the documentation first, if we document correctly, at any stage, the opportunity for misalignment comes to a halt. Now at scale, we can effectively manage the extensive network of APIs with Amazon API Gateway and SwaggerHub. Combining these two tools will help provide the API end users with a rich API, documented with notable examples, hosted on the lowest-possible latency with flexible security and monitoring capabilities.