LinkedIn
Twitter
Introduction
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
- Who is the audience for the specification?
- How will the specifications be built and maintained?
- What level of detail should be covered in the API Specification?
Participants
There are a number of different participants to be considered when defining an API Specification
API Consumer
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 Developer
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.
Target Developer
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.
Product Owner
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.
Proxy Maintainer
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.
API Specification
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.
User Manual
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.
Caching
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?
Analytics
What elements of the request or response are to be captured by Apigee analytics?
Traffic Management
What Traffic Management (Quota or Spike Arrest) policies are to be applied to API traffic?
Logging
Which API calls should be logged and what information should be captured?
Mediation
Information that API Developers will need to understand when mediating the initial API request and subsequent API response.
Typically this will cover
- Security to the Target
- Flows between the initial request and target interaction(s)
- Payload Mapping
- Northbound -> Target
- Target -> Northbound
- Management of Traffic Management policies
- Error handling (mapping) details
Configuration and Maintenance Manual
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
- Key-Value Maps
- Caches
- Target Servers
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.
Reference Manual
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.
Authorization
How is access to the API to be controlled.
Resources
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 |
Request
- Headers
- Parameters
- Example request
Response
- Example
Errors
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 |
Example Specification
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
Specification Detail
How much detail should there be in the API Specification?
This will be determined by a number of factors
- Maturity of the Team A less experienced team will likely need more details on the specification about how the API is to be developed, but avoid the trap of the Specification getting into micro levels of details an rely on the following other artefacts to help the team.
- User Story 'How' vs API Specification When it comes to building the APIs, we would recommend building out the Product Backlog by defining User Stories that define the business value that we're trying to derive. This is know as the 'What' of the users story e.g. As a XX I want to YYY so that ZZZ. The User Story should also define a 'How' which should reference the relevant part of the API Specification, but also provide some guidance as to how the feature should be implemented. As above the level of detail required will depend on the maturity of the team but as general guidance on what should be specified in the User Story vs the API Specification, consider if the information is transient or will be needed by future developers. If the information is only useful at the time of initial implementation then it's probably not worth adding the to the API Specification.
- Common API Requirements Certain functionality may be required across a number of APIs e.g. logging to Loggly. Rather than documenting this in each API specification, document this under a a Common set of requirements and reference from the Specification. Another benefit of documenting you API in a Wiki is that it's easy to link these kinds of documents together or include content from one page in another.
- API Best Practices Similar to above, if you have best practices about how you want to approach certain problems across all APIs, then document this in a central location and reference this from your User Stories in the How section rather than re stating. e.g. How error should be mapped from Target systems into a consistent format to be presented through the API. Using tools such as JIRA and Confluence make it easy to link User Stories and Best Practice documentation together.
API Catalogue
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.
API Maintenance
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
Summary
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?
