Consume and Analyze an API
--
The Apiary team created an interactive microsite detailing this design-first approach to building APIs. I was part of the content creation, including formatting this microsite into a whitepaper and a series of blog posts to be used on Oracle’s Integration marketing platforms.
Oracle Apiary believes in a design-first approach to the workflow of building APIs. One of the key components of this method is constant communication with all stakeholders to agree on things like API descriptions, architectural styles, and style guides.
The phases of building an API include Preparation, Design & Prototype, Development, Delivery, Consumption, and Analysis. The Development and Delivery phases should come after the API is prepared, designed, and prototyped. This post will walk you through the Development and Delivery phases. Follow this series for more posts on API Design and Development.
Consumption Phase
At this point, your API is implemented and deployed. Your API users can start working on the client, but they do not have to wait until the API is developed to get started. With the Apiary Mock Server, they have a prototype and a stub implementation of your API that can be used to build the client.
In this phase, your API users will build their clients with the help of the tools Apiary is providing.
Use Apiary Documentation
The first step to understand an API is to read its documentation. A wise man once said: “An API is only as good as its documentation”. That is why Apiary automatically provides your API with the best API interactive documentation.
To start consuming an API, read its documentation and identify the parts of the API that you want to interact with.
Use Apiary Documentation Console
The Apiary Documentation console enables you to interact directly with your API without the need to leave the documentation.
With the console, you can make API requests to learn about the behavior of the API and how to use it.
Use Apiary Traffic Inspector
Apiary Traffic Inspector is a debugger for your client’s calls. With it, you can pinpoint where a problem is in a client server communication.
With every call, you see what data has been sent by the client and what was sent by the server in response.
Every call from any client to the Apiary Mock Server is recorded. You can also monitor calls made to your deployed API using the Apiary Proxy feature.
Develop Client with Apiary Mock Server
With Apiary Mock Server you can start working on your API client before (or in parallel) to API development.
Just point your client to the same Apiary-hosted stub implementation you have used to verify your API design in the Design and Prototype phase.
While working on the client, you can use the Apiary Traffic Inspector to debug the traffic between the client and server.
The sooner you start working on your API client, the sooner you might discover and address potential problems with your API design and the sooner you will deliver your client to the market.
Develop Client with Apiary Proxy
If your API is already developed and deployed, you can build your API client using the Apiary Proxy.
The Apiary Proxy feature relays your requests made to your deployed API. It also records all the traffic and reports it to the Apiary Traffic Inspector for debugging.
Analysis
The work is never done. Measuring the API usage and listening to the feedback during every phase is the key to a successful API.
Collect Feedback
There are numerous ways to collect feedback about your API. Every phase of the API design workflow involves different stakeholders working on the API.
During the Design and prototype phase the input from API product owners, organization architects and API consumers is essential for good API design. The Development phase brings challenges to server developers. Their feedback might help improve both performance and security of the API. Finally, the Delivery and Consumptions phases put your API to the ultimate test by its users.
During this phase, you may learn if the API is delivering what was expected, verifying it as a product.
Iterate
Analyze the feedback during every phase. Often, the input can be immediately reflected in an updated version of your API design, restarting the API workflow.
You do not have to wait until all the phases are passed to address a feedback. Thanks to Apiary, you can can quickly iterate in your API workflow. With the integrated tools you can rest assured everything is up-to-date with any API description change. And if your API implementation gets out of sync, you are immediately informed thanks to the testing in CI.
It is difficult to come with the right API design in the first pass of your API workflow. Do not hesitate to iterate over and over through the whole API workflow and its phases. Apiary has you covered.
To learn more about a design-first approach to building APIs, check out Apiary’s how-to site called How to Build an API.
