Blueprint: Generate OpenAPI Using Code Annotations

This is a blueprint for entering the API lifecycle by generating an OpenAPI using code annotations, taking a code-first approach to bringing each API to life, while still ensuring that there is a contract to help guide the API across a more standardized API lifecycle.

Not all APIs and the teams developing them are able to embrace a design first approach to delivering APIs and sometimes it makes more sense for developers to write the code first, then provide annotations within the code that can be used to generate OpenAPI definitions for each API as part of the regular build process. It is important that there is an OpenAPI contract for each API, so that documentation, mocks, testing, and other elements can be generated, but not all teams will be able to hand-craft the OpenAPI from scratch. Making code annotations a valid approach to developing an API using a code-first approach, but still realizing the benefits of having an up to date machine readable contract present for each API as it evolves throughout the lifecycle.


Define

The most important first step of any API lifecycle is to make sure the operations around an API are properly defined, laying the foundation for being able to effectively design and bring an API to life, while also establishing a known place, or places to go to get all the information you need regarding each individual API, or groups of APIs. A little planning and organization at this early step of the API journey can go a long way towards ensuring the overall health and velocity of an API, and the applications and integrations that will depend on each internal, partner, or public API being delivered.

  • Team Workspace - Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across it's entire lifecycle.
  • Team Members - Formerly defining who the team will be moving an API forward through all stages of it's lifecycle, providing a clear definition of who is responsible for each part of producing an API.
  • Github Repository - Having a dedicated Github repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.

Deploy

The road to setting a new code-first or existing API on a road to a standardized API lifecycle often times begins with the generation of an OpenAPI from annotations in the code as part of a build process. Relying on annotations for each code method to produce an API for the surface area of the API, updating the OpenAPI, and other supporting documentation and tests using a CI/CD pipeline. Bypassing the API design process and going with a code-first approach to delivering an API, and relying on the pipeline for the existing software development lifecycle to generate the OpenAPI, and set in motion the delivery of documentation, testing, and other elements of the API lifecycle.

  • CI/CD Pipeline - Like other aspects of the software development lifecycle, APIs benefit from well defined, repeatable CI/CD pipelines to deploy, test, automate, and orchestrate throughout the API lifecycle, publishing APIs to development, staging, production, and other stages, but then also ensuring other elements like publishing of documentation, and tests are baked into the process.
  • Code Annotations - Language specific code annotations can be used to generate OpenAPI definitions for APIs in a variety of programming languages, allowing developers to provide the necessary information to create an APi contract from within their natural development environment, embracing a code-first approach to the API lifecycle while still ensuring there is an OpenAPI to be used for the rest of the lifecycle.
  • OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.

Document

Having complete, accurate, and easy to follow documentation is essential for all APIs, and is something that alleviates the number one pain point for API consumers when it comes to onboarding with any API, expanding the number of API paths an application puts to work. Modern approaches to producing API documentation have moved beyond a single static version of documentation simply published to a portal, as well as there being potentially multiple forms of documentation for any single API. Helping API producers onboard consumers easier, reduce the cognitive load when understanding what an API does, and properly define specific business use cases of an API being put to work in an application or as part of an integration.

  • Reference Documentation - It is helpful for API consumers to have complete documentation for the entire surface area of an API, providing a complete reference of what is possible with an API to help consumers explore every path, parameter, schema, and other details of how an API works, making the resources and capabilities available within API something consumers can find and put to use without much work.

Test

A test-driven API lifecycle ensures that each API delivers the intended outcomes it was developed for in the first place, providing manual as well as automated ways to ensure an API hasn't changed unexpectedly and is as performant as required, helping establish a high quality of service consistently across all APIs. API testing should not be an afterthought and should be a default aspect of the API lifecycle for any API being put into production. API testing takes a solid investment in establishing proper testing practices across teams, but once you do the work to establish a baseline of testing, properly train teams on the process and tooling involved, the investment will pay off down the road.

  • Contract Testing - Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed, providing a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.
  • Performance Testing - Performance tests can be defined as individual tests using collections, pulling from one or many individual API paths and measuring the time it takes for the response to be sent, providing a test that can be run manually, scheduled across multiple geographic regions, or executed as part of a CI/CD pipeline, helping ensure an API is always meeting it's expected performance benchmarks.

Secure

Security must be its own area of the API lifecycle, but it is something that should span testing, authentication, and potentially other areas of the API lifecycle. Over the last five years the world of API security has expanded, while also moving further left in the API lifecycle as part of a devops shift in how APIs are delivered. There are a number of elements present when it comes to security, but depending on the overall maturity of API operations the available resources and prioritization available to adequately realize these elements vary.

  • Authentication - The consistent application of standard authentication as part of a standardized API management layer striking a balance between access to digital resources but ensuring that undesirable actors do not have access to valuable assets.
  • Security Testing - Security tests can be defined for any API using executable and shareable collections, testing for common OWASP vulnerabilities, as well as other more custom scenarios or business approaches, providing a single or suite of security tests that can be manually run, schedule across multiple regions, or executed as part of a CI/CD pipeline, automating security consistently across APIs.

Monitor

Monitors can be used to execute any Postman collection applied to any environment. Due to the versatility of what a Postman collection can define, collections turn monitors into a powerful API automation and orchestration tool. Beginning with the ability to schedule contract, performance, and other types of tests, but then also allowing for automating specific workflows across many different APIs. Since collections can be used to define anything that can be defined via an API, monitors can be used to schedule the running of each capability from multiple cloud regions, applying many different environmental variables. Making monitors an essential, versatile, and executable part of defining how the API lifecycle works.

  • Contract Testing Monitor - Monitors can be setup for all API contract testing, scheduling the run of contract testing when needed and configuring to run from the regions that matter most to business operations, making sure that each individual API contract is never breaking with consumers, making sure that each API is delivering as expected on a 24/7 schedule.
  • Performance Testing Monitor - Monitors can be setup for all API performance testing, scheduling the run of performance testing when needed and configuring to run from the regions where performance makes the most difference on business, making sure that each individual API SLA is met, identifying API performance issues early on and responding to ensure there is no significant business impact.
  • Security Testing Monitor - Monitors can be setup for all API security testing, scheduling the run of security tests when needed, making sure that each individual API is regularly certified as being secured, ensuring that APIs do not become a liability due to changes, but also keeping all APIs compliant with the latest level of security testing that is occurring across an entire organization.

Discover

The ability to discover APIs at all stages of the API lifecycle is essential for reducing redundancy across operations, helping teams find existing APIs before they develop new ones, properly matching API consumers with the right APIs, while supporting documentation, relevant workflows, and the feedback loops that exist as part of the operation of APIs internally within the enterprise, or externally with 3rd party developers. API discovery does not live at the beginning or the end of the API lifecycle, but should be considered across all areas of the API lifecycle, ensuring that APIs, as well as the operations around them are as discoverable as possible, but well informed when it comes to privacy, security, and terms of service.

  • Search - Ensuring APIs are always available via search helps make sure that APIs can be found by consumers, but also by other producers who are looking to develop similar APIs, making search for APIs, as well as the operations around each API a critical aspect of the API lifecycle that should be considered as early on in the design and development of an API, but at least as it is deployed into production.
  • Private Network - Private API networks all organizations, groups, and teams to establish private catalogs of APIs, collections, and the other artifacts and elements around them, making it easier for producers and consumers to find APIs that are being designed, developed, or operating in production, making APIs more accessible but only to an intended audience.
  • Public Network - Public API networks allow for teams, APIs, collections, and other elements to be made available for searching and browsing by a public audience, helping API producers reach a larger audience, but also allowing consumers to quickly find the APIs and other resources they need in their applications and integrations, networking consumers with producers in an ongoing and collaborative way.


Discussions

YAML

Printable

Return to Main Page

This provides a link back to the home page if you need it.