Develop and Deliver an API

The Apiary team created an interactive microsite detailing this design-first approach to building APIs. I was part of the content creation, including formatting this microsite into a whitepaper and a series of blog posts to be used on Oracle’s Integration marketing platforms.

Oracle Apiary believes in a design-first approach to the workflow of building APIs. One of the key components of this method is constant communication with all stakeholders to agree on things like API descriptions, architectural styles, and style guides.

The phases of building an API include Preparation, Design & Prototype, Development, Delivery, Consumption, and Analysis. The Development and Delivery phases should come after the API is prepared, designed, and prototyped. This post will walk you through the Development and Delivery phases. Follow this series for more posts on API Design and Development.

Development Phase

In the Development phase, the API implementation is built according to the design established in those first phases. The API implementation will be automatically tested against its design, ensuring that all stakeholders can see that it’s living up to the agreed upon contract.

Put the API Description next to Implementation

Once approved, the API Design you have created in the Design and Prototype phase represents a contract with everyone involved in the API lifecycle. You can think of the API description as a formalized agreement between the API provider and API users or the API product owner and API developers.

Make sure to stay consistent: if the contract (API design formalized in the description) changes, you’ll need to verify the implementation is still matching the contract, and vice versa. To make the monitoring of the contract and implementation changes easier, we suggest that you put the API description into the same repository as the implementation.

Apiary comes with seamless GitHub Sync to keep your API description stored on GitHub in sync with Apiary. If you want to utilize the GitHub flow while you are working on multiple versions of API descriptions, you can take advantage of the complete Apiary GitHub Integration. In either case, make sure your API description is right next to the code so you always know what the implementation should conform to.

Develop the Server

Finally, the moment we all love: writing the code! It is completely your choice what programming language, framework, or platform you are going to use to implement your API. The hard work of writing the implementation is up to you, but Apiary is here to help you verify your implementation.

The next few steps will teach you how to test your implementation locally or as part of a continuous integration.

Test the Server Locally

Testing an API locally with Apiary is easy. You do not have to write any tests because you already have your API description. Use Apiary’s open source API testing framework, Dredd. Dredd is a language-agnostic command-line tool for validating an API description document against backend implementation of the API.

Dredd allows you to test your API implementation locally against its API description in an instant. After you install and set up Dredd, run:

$ dredd

The Dredd tool will start a local instance of your server, take your API description and exercise every endpoint found in the description against the locally run server. It will report any disparities and errors. Whether you want to test at leisure or as part of a test-driven development workflow, Dredd is here to help.

Test the Server in CI

Once you are familiar with the local testing with Dredd, you can set a continuous integration (CI) service to test your API implementation. Dredd and Apiary support all of the popular continuous integration services.

Applying continuous integration and hosting your API description in the same repository as your implementation enables automatic test runs when anything changes. This assures your API implementation is in accordance with the API description.

Set up a continuous integration in your API implementation repository to be sure that your server is always implementing what is established in your API description.

Use Apiary Test Reporter

To help you even further with the testing of your API Implementation, Apiary offers the go-to place for your API test results. Regardless of whether your tests were run locally or in a continuous integration, Apiary Test Reporter offers a comprehensive and easy to use overview of all API Implementation tests.

Deploy

With everything implemented and tested as described in the API description, you can deploy your API. No matter where you deploy your API, it is a good idea to add both operational and functional monitoring so you can follow the health of your service and analyze the API usage in the Analysis Phase.

Delivery Phase

With your API implementation developed, tested and deployed, it is time to deliver it to the clients. You can share your API with its users in many ways, from handing out the API description to providing them with a beautiful customized interactive documentation.

Share the API Description

The simplest way to deliver your API to its users is to hand them the API description. Some of the API description formats are easy to read and others are easy to be processed by another program.

If your project is open sourced on GitHub, provide the link to the API description repository so you can get comments directly from users or maybe even a pull request.

Share the API Documentation

We believe the best way to deliver your API is to hand out the Apiary Interactive API Documentation. To do so, simply copy its URL and share it with your API users. This is as simple as sharing your API description directly, but it will provide the user with a much better experience than reading an API description and there are many tools to help in using the API.

If you are using Apiary GitHub Sync and your GitHub repository is public, your API users will be able to see its API description and submit pull requests to it. Do not forget that your Apiary Interactive API Documentation is always in sync with your API description on GitHub, and if you have set up the continuous integration it is always tested.

Embed the Apiary Documentation

If you would like to embed your Apiary Interactive Documentation in your website and customize its look and feel, you can do so with the Apiary Embedded Documentation.

Some great examples of embedded and customized Apiary Interactive API Documentations are Akamai’s Connect API, Microsoft’s One Note API or CSAS’s developers portal.

If you are interested in embedding your Apiary Interactive API Documentation contact us.

API Management

Based on your organization’s requirements, you might want to employ an API management system to publish, promote, and monitor your API. This may also include the support of API consumers.

There is a plethora of API management tools and solutions. We suggest picking a solution that best matches your needs and plans for the API. If your organization is already using an API management tool, you may embed Apiary Documentation in it.

To learn more about a design-first approach to building APIs, check out Apiary’s how-to site called How to Build an API.