The API design process comes with its challenges. One of those challenges is trying to determine if the API design is sufficient enough for what your target developers and end-users will need. Another is to ensure that the design is easy to understand and use. Let’s take the guess work out of your API design by exploring three ways that you can try out your API design before you start coding the production implementation.
1. API mocking
One of the easiest ways to explore an API design before writing code is to write a static version of your API requests and responses. These static mocks capture XML or JSON payloads as examples for yourself and others to view and make improvements upon.
Below is an example of an API operation request/response that retrieves the details for an import job process:
GET /v1/import-jobs/7937
HTTP/1.1 200 OK
{
"jobId": "7937",
"status": "InProgress",
"percentComplete": "25",
"suggestedNextPollTime": "2018-10-02T11:00:00.00Z",
"estimatedCompletionTime": "2018-10-02T14:00:00.00Z"
}
Creating a static mock of an API operation that retrieves a resource representation is quite useful, easy to build, and provides opportunities for plenty of feedback. In this example, we may decide that we need to add a few additional properties to support the desired user interface.
You may also wish to serve your static mocks using a web server, such as Apache or nginx, to allow front-end developers a chance to integrate your design early. They will be able to provide feedback early and often as they start to parse and integrate your static prototypes into their code.
Without the implementation code, static prototype integration will be limited to GET requests only. Tools such as Tyk’s mock response plugin can help you support mock responses to other HTTP methods, such as POST, without the need to write code during the design process.
2. Throwaway prototyping
Constructing a throwaway prototype provides further validation of your API design. Unlike a static prototype, which is often limited to GET support, you can code an API prototype with all HTTP methods, such as POST, PUT, etc.
Below is a snippet of Ruby that can generate a hardcoded response to a POST:
require 'sinatra'
post '/jobs' do
# return a response that simulates creating a new job
status 201 # created
{
jobId: "7937",
status: "InProgress",
percentComplete: "25",
...
}.to_json
end
You can use any preferred programming language/framework, though scripting environments such as Ruby, Python, PHP, and Node.js are all good choices as they offer fast development. Just keep the prototypes simple at first. Expand the prototype as needed to deep-dive into any contentious areas that need further exploration.
3. README-driven design
README-driven design provides an alternative prototyping style without the need to write code. Unlike a static prototype, a README file is created to demonstrate how to use an API to accomplish an outcome, rather than integrating with a single API operation. README-driven design validates your API design before you start to write code that will be more expensive to change later if you need to make a significant design change.
## Create a new job and check its status
1. Create a new job
POST /jobs
{ ... }
HTTP/1.1 201 CREATED
Link: ...
{ ... }
2. Use the Link header to request the job's latest status
GET /jobs/1234
HTTP/1.1. 200 OK
{...}
Using this approach gives you time to think through the API design and how it will be used to produce outcomes – without the overhead of writing or changing code. It also increases the quality of documentation and the surrounding conversations about the design. README-driven design can be thought of as the hand-written version of an acceptance test using BDD frameworks such as Cucumber.
Wrap-up
API design is a mixture of patterns and subjective design decisions. What makes sense to you, as the designer, may not make sense to others. Take the time to mock your design using one or more of the techniques outlined above to put your API design to the test. You may find out some interesting things about what your target developers and customers require. This will save you both time and rework that would otherwise be required to fix code you’ve already written.
