Accomplish a new API documentation via Postman in 1 click

In accordance with the basic definition of API and Wikipedia, an API or Application Programming Interface is an interface that allows two or more computer programs to communicate with each other. This is a type of software interface that provides services to other pieces of software. But I will not devote this new publication to defining or expanding upon something already defined. Arnaud is the technical founder of timeNough and I prefer to leave it to him.

In this article, I intend to discuss our recent accomplishments with a tool or service known as Postman, which simplifies each step of the API lifecycle and streamlines collaboration. As it is well-known and reputable in programmers’ communities around the world, Arnaud introduced me to it, and I was blown away by how much time we were able to save. We used it for only one purpose: describing in detail to a public of developers how to use the brand new API of timeNough’s prototype, HTTP request by HTTP request.

https://docs.apis.timenough.com

In the first place, why do we need an API?

My understanding about why a project needs an API is that at some point in time, the project’s developers meet the developers of potential clients and clients, like an unavoidable step, and it’s quite easy to anticipate that when this meeting happens, the topic is: how will we work together in terms of code or computing software, if of course the project in question is software or has a software component. As a result, you can anticipate that the project developers used a specific language and environment, and the clients’ developers also used another specific language and environment.

To make things seamless and smoother, to facilitate the collaboration between the two parties or, in tech terms, to make the integration and implementation easier between both teams, someone one day invented APIs: something in the middle, often developed by the project developers at the destination of the client developers, in order to bond everyone despite the difference in technical environments. Consider the case where timeNough has been developed in Python for instance (which is not accurate), but the development team of client A has developed an entire system in Java, and the developers of client B has a system in C++. The API of timeNough will be the central entity, enabling everyone to communicate in the same way, execute the same series of operations, and most importantly, speak the same language.

There are currently several types of APIs available, with RESTful APIs being one of the most popular. HTTP requests and HTTP responses are the languages used in that type. Developers of the project are required to put in place a series of Web Service Endpoints, or URLs to be called, but not through a classic web browser, but from code, any code and programming language: C, C++, C#, Java, Kotlin, Go, Javascript, PHP, Ruby, Python, Cobol or otherwise. Then all of these languages are capable of making HTTP calls, which is a unique and basic feature. Lastly, a key component of these RESTful APIs is the JSON format, which is handled by all of them. The language of the client developers should be capable of handling HTTP requests and JSON data, which means your API for them.

A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to the reading, updating, creating and deleting of operations concerning resources.
TechTarget.com

This is how APIs or RESTful APIs became a central point of interaction where everybody can interact with the project without having to change his entire system, but by maintaining it. If one day timeNough developers meet the IT department of a client company C, and their environment is very specific and uses a unique language, they could simply end and kill any possible partnership since it would be too difficult see impossible to integrate and implement timeNough. There is no doubt that having an API opens up many doors…

A layer of available operations that sits on top of the system

With APIs, all parties will be on the same page and can communicate in the same way. However, what will be discussed through APIs? I add to my perception of APIs that actions and operations should be performed via APIs. APIs are not a centralized entity that is established solely for the purpose of discussing new technology trends. No, it is a place where a series of HTTP requests may be executed in a desired and well prepared manner, a place where data and information can be exchanged.

Our first API provides developers of any client company with the ability to retrieve data from their code and perform specific actions. We will decide if more things can happen and if more features can be added to the next version of our API. In considering it as a single entity, we are able to separate it from the prototype, as if it were two separate but connected entities. By placing it as a wrapper on top of the prototype, it can evolve at its own pace: if the first version of timeNough prototype has eight features, the first version’s API may only provide four features.

We may decide to develop nine new features for the next prototype, but just two for another version of the API, or keep the API as it is and allow it to evolve more slowly. Each has its own life and is distinct from the other. Billing can even be interesting. The prototype is available for free testing by anyone, however, the API can only be available to early adopters and clients who are interested in working with us, after multiple sales meetings. Here, the term “wrapper” refers to the prototype being the source, and the API of the prototype being the top layer above it.

In spite of the fact that they are independent, their relationship is logical: if you can do one specific thing with the prototype, then you will be able to do it with the API, because like a house, the roof is added after the foundation, not the other way around. This will not always be the case, but for the first version of the API, it has been decided to proceed in this manner. timeNough’s first prototype involves interacting with eight bots by sending them email or SMS signals; therefore, the timeNough prototype’s API involves interacting with the same 8 bots by programming and triggering HTTP calls/requests from source code instead.

Two GET, nine POST and one PUT

You may find these three words unfamiliar if you are new to the world of RESTful APIs and HTTP calls, but do not worry, they are widely used in the world of programming as a whole and easy to remember. GET, POST, and PUT are not acronyms, but rather the names of HTTP methods, a way for a programmer to differentiate among all the possible HTTP requests. I have identified 17 possible HTTP methods leading to 17 different types of HTTP requests that can be made from any source code in any language. The HTTP method name is simply defined in the request preparation and that is all. The seventeen names below are links that give you an idea of the purposes of each: GET, POST, PUT, PATCH, DELETE, COPY, HEAD, OPTIONS, LINK, UNLINK, PURGE, LOCK, UNLOCK, PROPFIND, VIEW, TRACE and CONNECT.

Since method names and the necessity to define them are part of the HTTP protocol and rules surrounding HTTP calls, you cannot change them, avoid them, or reinvent them. The developer who made the API for you will decide which HTTP method you need to specify, based on what the HTTP request should accomplish, and this will serve as an indicator for you (the person about to execute the request from your code) about what you can expect in the response or result. Each HTTP method has its own conventions and information available online. The GET HTTP method, for example, is used to read or retrieve a resource. PUT requests are idempotent, which means they produce the same result regardless of the number of times they are executed. HTTP POST method requests, on the other hand, will result in different results.

Whenever you execute an HTTP POST request multiple times, a new resource will be created, even if the data is the same. By default, these are the theoretical rules; however, every publisher decides on his own about the purpose and HTTP method of requests, and if he decides to use the HTTP POST method instead of the HTTP GET method, it will be up to him. As you can see from the title of this paragraph, the first version of our timeNough prototype API has two endpoints that can be accessed via the HTTP GET method, nine via the HTTP POST method, and one via the HTTP PUT method. Here is everything you need, please enjoy, we will discuss the tool used to publish it right after:

https://docs.apis.timenough.com

Whitelisting remains a key of the prototype’s core

Once an API is in place for delivering resources, delivering pieces of data, and executing features remotely, it must be hardened. In order to prevent abuse and wrongdoing, the API must be protected, secure, and limited in how it can be used by outside developers. This is when API authentication and keys come into play. Here again, API architects and providers are offered a variety of options: API key, Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, Hawk Authentication, AWS Signature, NTLM Authentication or Akamai EdgeGrid. We decided to start small with our first timeNough prototype’s API by providing a simple API key, which may be indicated as a HTTP header or HTTP request parameters in an HTTP request.

API keys are simple strings that will be generated and delivered manually to each developer of the client company who wishes to use the API. As there is no automated process for generating this key, human intervention is the only option for having a closer control over the number of keys available. We have established an email address for centralizing all API-related matters: dev@timenough.com, where all API key issues/requests should be directed, along with the API key limitations you wish, and whether the HTTP requests should be counted on a weekly basis, a monthly basis, a quarter basis or on a yearly basis. In the event that requests for API keys increase rapidly, we plan to implement a self-service flow for it, as many SaaS providers do.

Authentication and security will not be sufficient with the API key. We decided to cross it with the email address of a prototype user who has already been whitelisted. We have implemented and explained here a strong and unique system for securing the prototype usage. Accordingly, if the API is the wrapper of our prototype, we must follow it and even rely on it for the API usage. According to the API documentation, each API HTTP request must contain a unique HTTP request parameters: the “who” parameter, which is a string equivalent to a whitelisted email address. This is a requirement for any API HTTP call, so if you specify an email address that is not in our database, you will receive an error message.

curl --location --request POST 'https://apis.timenough.com/initialization/get-whitelisted' \
--header 'api_key: 6958e157-c621-43e9-b12b-daf391d90b55' \
--form 'who="email.address@to-be-whitelisted.com"'

It is actually a simple linking between the new API key and an already known and whitelisted email address when an administrator generates a new API. The duo will be required to authenticate each request, similar to a login/password, and if the password is incorrect, no resources, data, or features will be available. Moreover, the documentation mentions an endpoint or URL:

https://apis.timenough.com/initialization/get-whitelisted

One endpoint is specifically designed to perform additional whitelisting, such as a replacement of the initial form, available through classic web browsers and designed to whitelist any email address. Through one HTTP call, an already whitelisted user can whitelist his entire department or group of colleagues, but only one email at a time.

Postman is to thank for a well-designed documentation page

It was a tremendous task for us to prepare the architecture, the logic, and the Web Service Endpoints, and make it connected and compliant to our prototype without compromising its already existing use and security. The next step was to document API usage, the URL for each endpoint and how to access it. At that time, Arnaud told me about Postman’s paid Basic subscription plan, which costs $12 per month. He suggested that we use this plan for one specific purpose: to publish an already standardized set of documentation pages on a custom domain name, which is a feature included in this plan. Documenting and presenting your API also requires conventions and best practices, as you have understood. Though you can create your own webpages if you wish, an outside developer viewing the page will have few expectations for saying with smile and curiosity: let’s discover and learn this API together. Otherwise, he will inform you that your documentation is both unusable and unexploitable.

Among these expectations is the possibility to translate the way HTTP request should be executed in the programming language of his choice, since without having to deduct it or going somewhere else, he will see in front of him and quite instantly some code he knows, a language he speaks, and can copy it and paste it directly into his IDE without having to reload the page. As such, the documentation page should be developer-friendly and user-friendly, with descriptions of the endpoints, HTTP request parameters, HTTP headers, and any information that is useful to the developer. All of this was included in Postman’s Basic plan, which ultimately allowed us to save time. Layout and interface are already designed and ready in the right format, with a clear and light presentation. As you can see in the following video by Postman themselves, the publication of documentation and interfaces is a relatively straightforward process.

Everything began with Postman’s desktop app, which you will have to download for maximum convenience, and a key proper element called Collection. A Postman Collection was created where we could add one or more Postman Requests inside it, another key component. Essentially, these Postman Requests are the endpoints of our API through which developers can make HTTP requests. The interface is quite intuitive and it is easy to understand the possibilities and instructions step by step as you add yourself. This was done for the 12 HTTP requests discussed earlier. Each time, Postman allows you to test the Postman Request and perform a real HTTP call with the resulting HTTP response. They even added the possibility for each Postman Request to add multiple Postman Request Examples, which is designed to separate different figure case based on the HTTP response. For instance, if your API returns a positive JSON response for one HTTP request, it indicates that everything has been okay; however, if the API returns a negative JSON response for the same HTTP request, the API will be unable to process the request.

Any changes you make to Postman are saved, so you will not lose anything, and once all endpoints, examples, and cases are defined, it allows you to convert your entire Postman Collection into single-page documentation that is well-presented, elegant, and slick. It is explained in the video that you begin by selecting your Collection and click on the Documentation button on the right. At the bottom of the side drawer, you will find a link that reads, “View complete collection documentation“, and clicking on that link will take you through a quick and effective process of publishing the documentation to your custom domain. Our Postman account was configured to include apis.timenough.com as a custom domain, we followed the DNS requirements and updated our DNS provider, and that is all it takes. Postman does his cuisine, publishes the URL and updates it when the Postman Collection is ready for public sharing.

https://docs.apis.timenough.com

I hope by reading this post you will give Postman a try when you are about to work on the documentation of your API, regardless of the language you choose as the source. As a result, you should now be better able to understand and argue the importance of APIs if you intend to sell a software product, as well as how online tools can sometimes be crucial to your success.
Thank you for your attention.