everythingpossible - Fotolia
Accelerate API dev with documentation-driven development
A missing cloud API doesn't mean all work needs to stop. Engineering and development teams can work with a mock API server until the real API is production-ready.
Enterprises should take a documentation-first approach to API development. While test-driven development emphasizes well-written and designed code, documentation-driven development considers the usability of a public-facing API.
Documentation-driven development enables dev teams to take into account everything from acceptance criteria to UI and user experience before they actually write a line of code. However, it can slow down the initial development cycle. Teams that are dependent on the newly designed API might get blocked until these documentation-driven developers build the API.
For example, when you build a new API, a quality assurance (QA) team might design and build a test suite to execute against it. While they can use the API documentation to accomplish this task, there is little to no feedback loop, and the QA team is left to hope that their work is up to par when the API is finally available to test.
An introduction to API mocking
Because productivity is paramount in an enterprise, engineering teams need to remove roadblocks to software development. In the case of a missing API, teams should validate the documentation -- as well as the subsequent implementation and integrations -- early, often with API server mocking. As the name implies, a mock API server is essentially a dummy server that accepts sample requests and returns valid responses so developers can work against a nonproduction API.
While some organizations build and establish a mock API server internally -- to reduce code and increase productivity -- some select third-party tools, like Postman and Stoplight, that easily and efficiently create a mock API server. In the API mocking process, documentation must stay in sync with the mock server.
API Blueprint is a web API description language. The Markdown-based documentation specification empowers developers to document APIs in a concise, yet expressive manner. For example, tools such as Drakov and Oracle's Apiary can interpret and process API Blueprint documentation and automatically deploy a mock API server.
Create a mock API server
To better illustrate the value of a documentation standard, such as API Blueprint, for documentation validation, let's spin up a mock API server using some basic API Blueprint documentation and the open source tool Drakov.
First, create some documentation. As for any documentation-driven development project, include information such as endpoints, parameters, responses and validations. For example, here is the spec for a simple Hello World API:
Next, with documentation in hand, install Drakov with Node Package Manager (Npm):
npm install -g drakov
Now, all that's left to do is to spin up the mock server with the Drakov command from within your documentation directory:
drakov -f ./*.md
Drakov spins up a basic web server on port 3000 with all of the defined routes within the API Blueprint documentation set up as endpoints:
As the mock server runs, validate the newly defined endpoints using the curl command:
curl http://localhost:3000/api/hello/42
The above command makes a request to one of the new API endpoints, which enables the developers to verify the endpoint nomenclature, as well as the response format and data. As defined in the API Blueprint above, the request should receive a simple object back with the "Hello:"
With the defined endpoints, you can also make a request to the top-level resources endpoint:
curl http://localhost:3000/api/hello
This command returns the expected array of objects defined in the Blueprint:
This simplistic example of documentation-driven development with API server mocking shows the potential power of this approach. With a feature-rich mock API server tool, such as Apiary, and even other API Blueprint-compatible tech -- try the Dredd language-agnostic command-line tool -- developers can design sane and logical APIs without disruption to a typical product development lifecycle.
