API Development Guide and Support

Consuming APIs is something with which all developers are familiar. Increasingly, you’ll also find yourself building APIs. Whether for your own consumption, for others in your organization, or even for external developers, your development processes can help you build a better API.

In this guide, we’ll show how planning, testing, and automation can support your API development. Build on top of an API description, such as an OpenAPI document, and you’ll more easily be able to create and maintain your API. It’s beyond nice-to-have documentation, it actually makes your development life easier, taking less of your effort than a less structured approach and causing far fewer headaches.

The start of any API development project requires a clearly defined purpose. Who are the intended users? What data or services will you interface? How you create this initial roadmap will dictate how all users will use and interact with your product. Even in code-first builds, all APIs start with a blueprint or reference template that describes their intended use.

If you have ever built an API or been a part of a development team working on one, any one or all of these different methods might look familiar to you:

• Google Docs: It’s familiar and has room for images, tables, and as much as you want to write about your API plan.
• Spreadsheet: You can get right down to route planning, listing every method, URL, and response types in an orderly grid.
• Wiki: You open up a page right in your GitHub repo and start hammering out everything your API will need to include.
• UML Diagram: Maybe you prefer clear diagrams to capture the intricacies of the routing and requirements.
• Cocktail Napkin: Or you’re a messy thinker, so you scribble notes on the nearest scraps of paper, detailing the API in your head.

No matter what you use, you have some way to describe what’s in your API before you build it. The problem is that once the development work has started, the code base diverges from this initial plan, which becomes a reference material that is increasingly inaccurate due to revisions and the realities of the development lifecycle.

The code and design documents are only as faithful to each other as the resolution to maintaining both documents.

Another problem arises in that there are now two sources of truth. When there is conflicting information, which document should be adhered to? Rework the code, or amend the blueprint? Consider adding testing and a Postman collection to the mix, and now there are four documents to reference, track, and amend when any changes are made.

Instead, imagine that creating the API plan and schema were the same thing. With the increasing adoption of schema specifications such as OpenAPI V2 and V3 (V2 formerly known as Swagger v2.0), new tooling and support for this human and machine-readable format have rapidly advanced. API planning and design tools continue to mature and now easily support open source solutions for graphical modeling, documentation, validation, and mocking, all from your API schema.

One benefit of working with an API contract like OpenAPI is the ability to generate usable code from this format. The OpenAPI Specification is increasingly the standard of RESTful APIs, a project overseen by the Linux Foundation. Companies such as Google, Microsoft, and IBM currently contribute to this open source format and are helping to promote it. Tools continue to emerge from this large community to leverage OpenAPI, including OpenAPI Generator for stubbing API code.

OpenAPI Generator only needs an OpenAPI 2.0/3.x document to generate client SDKs, mock servers, or documentation. This preserves the original document as the single source of truth. One change to the code no longer requires you to spend your entire life repeating the contract ad nauseam, changing the validation code, the integration tests, and the documentation in an endless loop. With this many different sources to keep track of, mistakes are bound to happen. Making edits at scale can now be as simple as rerunning a few CLI commands and regenerating the project files with the updated changes. No more bug hunting from a missed route change.

Leave the heavy lifting to the tools to free you from the syntactic ‘how’ of your API and devote more to the ‘why’. OpenAPI Generator can create server stubs in over 40 languages and technologies with a few CLI commands. From these stubs, you can begin the work of connecting your data and ensuring the API performs the right actions in your systems.

Your OpenAPI document remains useful even after your routes have been set up. It remains a part of the API development process and can be especially helpful in validating your response data against the design schema.

When you plan your API with an OpenAPI document, you can immediately reap the benefits with generated code. Based on the OpenAPI Initiative pet store example, you can see how to stub out your code with only a few terminal commands.

OpenAPI Generator can be installed many ways, including through npm:

To stub out your code, you’ll need to decide which of the supported languages and frameworks to use. In this example, with Express.js, a .jar of the OpenAPI Generator is needed as well as Java 8+ installed locally on your machine. The OpenAPI Generator README goes into more details on how to fulfill the requirements.

Here’s the command required to generate the stubs:

This command will:

Review the various files to see the routes, controllers, and services that make up your new API stubs. Of course, it’s just a start. You can reorganize the code however you like, but it’s likely saved you a lot of time you might have spent writing boilerplate code.

Don’t toss out your OpenAPI document after you’ve generated code. There’s a lot more it can do to help you develop an API. You can use this machine-readable definition in many ways, such as to generate always-accurate documentation and pre-development operational endpoints. The OpenAPI description is a source of truth—as long as it contains truth.

There’s a development anti-pattern that assumes the code is right. If you get a confusing result from an API, it means the documentation is outdated. We’ve all experienced those situations where reality is different than the manual. When this happens, especially once an API is in production, the only answer is to trust the actual API responses. However, API development using OpenAPI does not have to be this way.

When using an API description as the source of truth, you have ample opportunity to catch these sneaky “documentation errors” much earlier in the process. By extension, you’ll confidently build the API you originally planned.

Developers are used to writing tests for their code. These “unit tests” ensure that a function produces the expected result based on predetermined input. Similarly, contract testing compares an expected response (based on the OpenAPI source of truth) and compares it to an API’s actual response. There are many types of API testing. Among them, contract testing can save you time throughout your API development and even beyond as you make updates.

Simply, contract testing hits every combination of endpoint and HTTP method with an example request. Then it compares the response, such as status code, headers, and JSON fields, to the OpenAPI definition. It gives you confidence that you’re building exactly what was planned. Further, since your API documentation will be generated from the same definition, nobody will have to wonder whether the API or the docs is accurate. Contract testing provides a process to avoid those costly and confusing errors.

For example, after moving on from API planning, you may learn new information about what you’re building. This is a normal part of development. As much as we wish we had all the information at the outset, things pop up. Reacting to the new information, you might update a field in either the code or the OpenAPI document. Contract testing would discover that the two do not match and alert you with an error. Now you can bring the two sources in sync, having side-stepped a future bug before it went beyond development.

You can build contract testing into your ongoing processes, as well. Run the tests as part of continuous integration every time you want to merge changes into the API codebase. Some refactoring won’t affect API responses, the tests will pass, and you can continue with a deploy. Other cases will be just like the development scenario and you’ll have caught a conflict before it could cause bigger issues for your team or customers.

Contract testing helps keep your API planning and API development in sync. By using an OpenAPI document as the source of truth, you ensure that everything built in its image is updated.

To get started with this type of API testing, you’ll need to compare live calls to the contract written in your OpenAPI. You can set up validations for your API using the open source CLI tool, Prism. You’ll also need your OpenAPI document and a version of your API running—could be in production, staging, or even your local machine.

Install Prism from your command line, then run validations like this:

Be sure to replace this command with your OpenAPI file (shown here as YAML, but it could be JSON) and a path to the API referenced by the OpenAPI.

For example, if your OpenAPI requires a name field in the POST data and one is not present, Prism will return a validation error:

Similarly, you can have Prism validate responses, status codes, and even the servers that it expects to see based upon the OpenAPI source of truth.

Another way to ensure your API development matches your API planning is to include other stakeholders early. As you stub out potential endpoints, you can share documentation generated from the current OpenAPI document. Even at this stage, everything is a hypothetical. That makes it tough for other team members, such as those who will consume the API in their applications, to know if what you’re building meets all of their use cases.

Mock servers provide a fast, flexible way to get early feedback on your API development. If you use a design-first approach, you don’t even need to write code before producing servers from your OpenAPI document. Even if you started with code, servers generated from API descriptions can be faster to stage on public servers. Plus, you don’t need to worry about populating a database or making up responses. The correct data type can be generated from your OpenAPI document.

There are a couple mock server tools we recommend:

• Prism, an open source tool maintained by Stoplight, which you can run locally or host yourself.
• OpenAPI mocking via hosted Prism is included in the Stoplight platform.

In either case, you can connect your mock servers to the latest OpenAPI document. When you update this API description in version control, you can automatically generate new servers at a temporary subdomain. Collaborators can then access the mock API via the exact same path and receive realistic API responses.

There is no standard API response format. Even within the JSON format for use in RESTful applications, there is no defined standard. This allows developers to tailor response data to the exact specifications and shape when building, but can leave other users behind when they try to consume the API. Even though there is no accepted single standard, many formats have emerged to create guidelines in how data and messaging should look. Picking the right one for your API needs may determine how your API will be consumed by others.

There are four main types of data:

• Direct Data
• Feed Data
• Manipulation Data
• Database Data

Within each type of data sent, there are multiple acceptable formats and use cases. APIs are the bridges between software products or users, so selecting the right format is critical. The right format makes your API useful.

• Machine-readable, forms the data upon request and handles data from service to service communications
• Supports sharing of data directly between systems
• Best used in B2B or public-facing API implementations

Formats include:

• JSON(JavaScript Object Notation)- client-side scripting, generally faster, supports data types
• XML(EXtensible Markup Language)- handles mixed content, mixed node arrays, 'kitchen sink' of formats
• YAML(YAML Ain't Markup Language)- "Middle of the road" between JSON and XML in complexity/speed, easily reveal hierarchies, minimal cruft

• Machine-centric but still can be used for human utility
• Useful for serializing changes and updating users to these changes
• Best used in subscription industries such as blogs, video sharing, and social media

Formats include:

• RSS(Rich Site Summary)- most widely used, very simple, "official" feed of WordPress,
• Atom- designed to mitigate RSS issues, more complex markup and media, more potential for security issues
• SUP(Simple Update Protocol)- faster than Atom, more verbose than RSS, "jack of all trades, master of none"

• Should be considered more a “wrapper” than a “format”
• Delivery service, not a parsing or translation service
• If an API handles locations, especially in terms of geography on a map service, KML must be supported
• If an API handles signature authentication services for documents, PDF support is required
• Best used in the design and communication-oriented industries

Formats include:

• PDF
• KML

• Handles communication between databases-to-database or database-to-user
• Takes generated data and archives it for later use
• Categorized and stored in database formats for interpretation
• Best used in analytic dependent or long-term data utilization implementations

Formats include:

• CSV(Comma Separated Values)- very common, made largely obsolete by XML, most often used to transform
• SQL(Structured Query Language)- great for storing data with file and relation structure, widespread enterprise adoption

Any over-the-wire format can be used. There are definitely more popular formats like JSON and RSS that will be readily recognizable, but others that will be unfamiliar. Some of those formats may be: ​- RSS - Atom - JSON:API - Siren - HAL - OData (Open Data Protocol)(RESTful) - Collection+JSON - FIHR (Healthcare) - GeoJSON (GIS) - RFC 7807: API Problems - Health Check Response Format

Modern software applications are increasingly complex structures that perform interconnected tasks with other services. Drafting your API plan on a whiteboard in the office cannot fully capture all the design requirements. It can't very easily evolve with the service, either.

New tools now integrate with standardized, machine-readable API descriptions to do the most tedious parts of the building and testing for you. It’s not exactly like writing the documentation first, but it is a source of truth that saves you time in the long run. And the artifact you create can write your docs for you. In addition, you get integration tests, mock servers, code stubs, and data validation for the lifetime of the product.