As companies scale the software they build, they also need to scale the number of APIs they provide internally and externally. However, without the right API governance practices and the right design workflow in place, several obstacles can reduce the design throughput of API teams. Here are four obstacles that can appear in your API design workflow and lead to lower quality APIs and increased software delivery lead times.
Obstacle 1: No business capability and resource model map for your APIs
Description
Are there documents that clearly describe the digital resources and business capabilities your APIs expose? When a new API change request is made, is there a documented resource model that can be used as a reference for the API design? Having API specification files and an API reference is not enough as they do not give internal API stakeholders a holistic view of the APIs. An API reference alone does not provide a clear outline of how enterprise business capabilities translate to the digital resource models and operations exposed by APIs, nor does it provide essential meta data to support strategic decision making around APIs.
To provide that level of comprehension, you need a different level of API resource abstraction; you need an abstract model that presents the view of the resources you want to present to your API consumers regardless of the API architectural style your web APIs provide (be it REST, gRPC, GraphQL, or SOAP).
Without this abstract resource model, API teams stand the risk of building APIs that have inconsistent naming of fields and resources or duplicate existing functionality in other APIs. Also, there is little chance of reuse and migrating API implementation technologies or architectural styles while maintaining the same enterprise resource views becomes more difficult. In addition, system architects and product managers may find it difficult to get important API metadata information they need to make decisions.
Recommendation
Start by mapping the business capabilities and abstract resource models of your APIs. These digital resources are long-lived structured views of the data you expect your consumers to understand and work with. They can be captured in a word document, spreadsheet or plain text markdown file. James Higginbotham’s Principles of Web API Design book is a good guide on how to go about this.
Alternatively, use a holistic API service catalogue solution like DitialML’s Ignite platform that provides this capability and incorporates advanced workflows. Regardless of the solution adopted, the key thing here is that stakeholders across the organisation (be they engineering, product, support, security or sales) can easily access, understand, collaborate on and get a consistent view of the key data structures and resource relationships consumers will be presented with via the APIs.
Obstacle 2: Lack of enterprise-level API discovery
Description
API discovery refers to the ability to find and use APIs in the enterprise. When an organisation’s API discovery capability is poor and API teams can’t find a comprehensive and up to date list of APIs in the enterprise, it’s much harder for them to build API integrations and develop innovative ways to combine the business capabilities exposed by the APIs. As the API Evangelist Kin Lane put it:
“If architects, business leadership, and any other stakeholder can’t browse, list, search, and quickly get access to all of the APIs that exist, the knowledge of the enterprise capabilities will not be able to be quantified or articulated as part of regular business operations.”
– From, ‘What Are Your Enterprise API Capabilities?’ by Kin Lane
Recommendation
Make it easy to discover and use APIs both for the external audience (via the developer portal) and crucially for internal stakeholders in the enterprise. One way to do this is to use an apis.json specification file. It provides a machine-readable way to show links to your API specifications and related metadata.
Of course, for services without API specifications, the first step is to create the specifications. You can consider generating the API specifications from code (for example, using SpringFox for Spring-based services). Where it is unclear how many API s you have on the estate, commercial tools like Akita and Traceable.ai can help discover these from runtime traffic.
Obstacle 3: Poor API-design-first tooling support
Description
There are great advantages to an API design-first approach. But a criticism of this approach is that API teams may think they have to write OpenAPI specifications by hand. And some popular REST API collaboration tools reinforce this view by presenting a ‘you-must-do-your-API-design-by-coding-in-YAML-or-JSON‘ user interface.
You can see how this can be a stumbling block for product managers, product owners and business analysts who may not be well versed in the OpenAPI specification. Many engineers I know do not like working with that kind of interface either.
Recommendation
There is no reason to write OpenAPI by hand. Tools like StopLight Studio and Apicurio Studio provide excellent, intuitive GUIs to enable anyone create and edit API specifications. More importantly, I would suggest decoupling API specification editing from its storage – they don’t necessarily need to be done in the same tool. Store your API specifications in a repository that does not restrict what tool stakeholders use to edit them. I prefer Git for this, as it gives API designers this editor freedom and enables a GitOps approach to automation (see next obstacle).
Obstacle 4: Poor API design workflow automation
Description
When there is no automation in the API design value stream (for example, the absence of API linting and breaking change checks), teams must rely on manual error-prone checks for API style guide compliance, and this prevents them from getting fast feedback on their API design. To be clear, there will always be a place for API reviews as API design is at its core, a design task. Design and modelling are not always easy to automate. But why spend precious time in API review sessions on the aspects of style guide checks that can be automated?
Apart from automating style guide checks, inspecting your API design value stream may reveal teams carrying out manual steps that can be automated from the API specifications. For example, writing client code that can be generated from API specifications. Of course, manual steps tend to increase process time and can introduce human errors.
Recommendation
Start by mapping out your API design value stream. Automate your API design workflow into a continuous delivery pipeline for your API design artefacts. Put in place a continuous delivery pipeline that reflects your API design value stream and produces your API specifications (e.g. OpenAPI, RAML, GraphQL, Postman Collections). Treat your API specifications as first-class delivery artefacts to API consumers. But design delivery should not end with just the specifications. Include the generation of any derived artefacts, for example API reference documentation, client and server stub code, and API release notes.
Conclusion
In this post I have presented four obstacles that can hinder the API design process. In removing these obstacles, I would recommend that obstacles 1 and 4 are good places to start. But ultimately removing all four will help accelerate your API team and deliver improved API quality for your consumers.