This article will cover some of the best practices that the Apigee Customer Success team follows when building an API specification.
This article will not cover the principals of a how to design an API but rather the practices we follow in documenting and managing the specification including the API design.
This is more than just the external facing / northbound definition but includes sufficient information required for API developers to build the API and API Maintainers to look after the API.
When starting your API Program and building your API specifications a number of factors need to be considered
There are a number of different participants to be considered when defining an API Specification
e.g. App Developers that will consume the APIs being exposed.
Ultimately the API Consumer facing documentation is best placed in a Developer Portal where developers can sign up for your APIs and test out your API.
As outlined by @Marsh Gardiner in his Blog Post A Design-First Approach to Building APIs with Swagger, an approach where the consumer facing definition of the API is defined first using a simple modelling language such as Swagger gets you off to a good start
A Swagger definition can then be used to build your API Consumer facing documentation e.g. using SmartDocs. One of the key benefits of starting with Swagger is that it's machine readable and so can be re used to automate the generation of other documentation.
Proxy Developers need more 'under the hood' information on how the API will be built once the external facing definition has been agreed.
This will include details such as how the payloads are to be transformed, what target servers are to be used and how traffic management will be applied.
The developer of the underlying service that's being exposed will need to be consulted in order to understand enough about the underlying service for the API Specification to be built.
It may be the proxy is just a very thin facade over the underlying service that already adopts the key principals that you'd like in your API.
It may be that the underlying service needs a lot of mediation to expose the functionality that is easily consumable.
The proxy itself may also orchestrate inputs from a number of underlying target services
In all the above scenarios input from the target developer will be key to building the API Specification.
The owner of the business requirements behind the APIs may not care about the low level technical details of the API, but will want a higher level overview of their overall API Catalog.
They will also want to be able to see a consistent approach to how resources are being exposed across APIs.
Once the API is in service, it will need to be maintained e.g. by a Support team or by the original Proxy Developers.
The cost of maintenance of an API is one of the key factors that will determine whether an API program can maintain the velocity required to be successful.
The way in which configurable elements of the API are documented allows Proxy Maintainers to quickly make required configuration changes, without redeploying proxies or relying on time from API Development teams i.e. configuration vs code.
These changes still need to be applied in a controlled manner but can be made outside of the traditional SDLC.
In order to cater for the different audiences above and also provide a coherent view of information across APIs, we recommend the use of Wiki based tool.
Wiki based tools allow a collaborative approach to building the specifications and also allow the information to be presented in different formats for the different API Specification audiences.
A single monolithic word document covering all your APIs or 10's of separate word documents do not foster collaboration, are difficult to maintain and do not provide an easy way to to link User Stories to API Specifications.
The API Specification should include any initial API design outlined in e.g. Swagger but build on this to provide the additional information required to build and maintain the API.
This document would usually be Wiki based and contains the functional API considerations that API Developers and Product Owners will need to understand, it can be considered as the Proxy's functional requirements.
The following is an example list of some of the areas that would need to be considered.
How are responses or parts of responses to be cached?
What will the TTL be for the cache be and how will this be maintained?
What elements of the request or response are to be captured by Apigee analytics?
What Traffic Management (Quota or Spike Arrest) policies are to be applied to API traffic?
Which API calls should be logged and what information should be captured?
Information that API Developers will need to understand when mediating the initial API request and subsequent API response.
Typically this will cover
Configuration and Maintenance information that API Developers and API Maintainers will need to understand
Typically this will cover the following items that are specific to this API such as
This provides a single place where Proxy Maintainers can look at the configuration options for this API that do not require proxy redeployment.
That's not to say these changes would be uncontrolled, changes to the above items could still be controlled through Management API calls triggered through a CI tool based on changes in Source or Configuration Control.
e.g.
aka Northbound Specification
Northbound / external facing specific information that API Developers, API Consumers and Product Owners will need to understand
This will be based around the model that was originally created for the API e.g. Swagger but will also contain additional information required for API Developers.
This layer of documentation should be automated as much as possible to allow the high level API design to be easily translated into external facing API Documentation.
How is access to the API to be controlled.
What resources are to be exposed in this API?
For each resource the following items are documented
API | API containing this resource |
Proxy | e.g. customer-v1 |
Base Path | e.g. /customer/v1/ |
Dependency | Any dependencies on other APIs |
Functionality | Description of the functionality e.g. Create a customer |
Verb | e.g. POST |
Resource | e.g. /customers |
Scope | e.g. customer.all |
What errors are thrown by this API?
For each error we would document
API | API throwing the error |
Resource | API Resource associated with the error |
Target | Target associated (if appropriate) |
Error Type | e.g. Not Found, Unauthorized etc |
Response Code | HTTP Response Code e.g. 404 |
Error Code | Implementation specific response code e.g. 404.03.001 |
Error Message | Example of the kind of error message returned |
Example | Example error payload |
The real value of building a specification in a Wiki based tool cannot be fully communicated in a PDF extract, but the attached example gives you an idea of what an overall specification might look like.
The following extracts from Confluence provide blank HTML and XML based templates that you can use to build your own API specifications. The XML template can be imported into your own Confluence instance.
template-api-specificationhtml.zip
template-api-specificationxml.zip
How much detail should there be in the API Specification?
This will be determined by a number of factors
Documenting the API in a Wiki based tool allows for the aggregation of resources and errors in one consolidated list which is useful for Product Owners, API Developer and API Maintainers.
e.g. Here's an example of a Wiki based report you can put together to view all the resources across all your APIs.
Information key to API Maintainers can also be aggregated in a similar fashion which provides the basis of a run book to be used by API Maintainers
e.g. Using Wiki based tools you can list all pages with a given label e.g. 'api-configuration' in one place.
This a key benefit of using a Wiki based tool for building your API Specification
1) Consider who your audience is and what they need
2) Use a Wiki based technology to foster collaboration and allow the presentation of the information in different layouts to suit different members of the audience.
3) The API Specification is a living document that will evolve and change over time, how will you manage it?