— by Hasan Karahan, CTO Percim.com
Providing fast and reliable digital services via a so-called Application Programming Interface (API) for integrator customers is nowadays standard. It allows a modern technology company to quickly enter a market, and start immediately adding value to its clients.
The basic idea is that the company sets up a server and offers a secure authentication mechanism; upon which then a customer client software can start to consume the provided services. An example of authentication could be a simple login screen:
However, for this to work this API between the server and the client systems needs to be thoroughly documented, in such a way that a customer can quickly gain an understanding of the offered technical capabilities.
It used to be the case – and it is still often so – that such documentation was a static technical manual being provided in print or via a simple digital PDF.
But, this also meant that expensive software developers integrating the client system had to laboriously study those manuals, and write their own code snippets to test an API to gain a better understanding of what is being specifically offered. This process of getting acquainted with the technicalities took time, and often still does so!
In recent years however things have changed, and software providers started specifying their APIs plus writing user interfaces consuming those formal descriptions to offer an interactive experience for their integrators. If done well, this form of support can result in dramatically shorter project durations and hence lead to higher success rates in terms of adoption.
An Overview of Percim’s API Explorer ¶
Now, at Percim.com we offer our brand new API Explorer (free of charge and open-source), allowing our current and future customers to rapidly acquire a deep understanding of our services:
Let’s go quickly through the various sections of our API to get an overview:
| Section | Description |
|---|---|
| OAS | offers an end-point to fetch the OpenAPI specification (a formal description of the API) |
| image | offers end-points to process images |
| extra | offers some miscellaneous end-points |
| debug | offers end-points for debugging |
As shown above there are at the moment four different sections in the current $1.0.0$ version of the API.
The user interface for each end-point can (i) be toggled on, (ii) the required (or optional) parameters can be filled in, and then (iii) a corresponding request to the server will be sent off, upon which (iv) the received response will be displayed.
Using the /now End-Point ¶
As an example let’s test if the API is running, by sending a request to the /now end-point (without any parameters), to verify that the server responds with the current time:
As shown above, the API indeed seems to be online and responds as expected with the current time of the server.
Terminal Interaction ¶
If we were to use a command line interface (CLI) in a terminal, we could achieve the same request/response interaction via:
$ http https://api.percim.com/now authorization:"$AUTHORIZATION"
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 36
Content-Type: application/json
Date: Fri, 29 May 2020 14:46:07 GMT
{
"now": "2020-05-29T14:46:07.396702"
}
…where the $AUTHORIZATION token needs to be acquired from an authorization server (such that the API server can then authenticate our request). Above, the API Explorer fetches this token automatically behind the scenes.
Download the API Explorer ¶
We will not further delve further into the specifics of the other end-points. However, you are invited to explore them for yourself by downloading the API Explorer from our release page on GitHub.com:
