Non-pain API integration — 10 features of a good API that make the whole process pleasant
How to implement an API in the company's systems? What to look for to know if the API has been well prepared for us?
Since growing business expectations and new regulatory requirements drive a growing number of API integrations in business, many internal IT departments face the task of implementing Application Programming Interfaces in their systems.
The implementation of an API, which later serves as a link between internal databases and CRMs and a network of data providers and partners, can in principle be twofold - pleasant as warm summer rain, or tiring like a night spent on a mattress with spikes.
And just like in real life, also during API integration, if something does not go as it should, then you either do something wrong by implementing the API, or the fault lies on the other side and the API has been poorly prepared.
How do you know who made a mistake?
For sure you already perfectly know that two different people can describe the same situation in such a way that it is doubtful whether it is actually the same situation.
Using our experience resulting from building API for business (National Polish Regsiters API, Hungary Register API, Czech Republic, Russia and many many more (VIEW LIST of APIs)), in this article we share knowledge on how to know whether the API has been well prepared or not.
Pool or trigger — how to start API integration?
Before we get into the details of the well-prepared REST API, one thing is important - determining how we want to run the API. We have already received from the API provider data for authentication and authorization necessary to run the service, and now it is time for us.
To check data transfer via API, one of two methods is generally used:
- we start active data downloading (so-called polling), i.e. we query the API for specific data, being completely responsible for the amount of downloaded data and control of this process,
- we set the so-called Webhook trigger, i.e. instead of asking the application for specific data, we "ask" the API to inform us about changes in the database.
The first method is easier and enables seeing how the API realy looks (what is data quality etc.), but has one major drawback. We are unable to check if the API works in real-time. We are simply downloading the whole database.
The second method, much more difficult from the implementation side, allows us to verify the operations of the real-time API. We send a request according to the given structure & available methods and observe how the API reacts. Nevertheless, it also has some drawbacks. Firstly, we are not able to control the amount of data sent to us. Secondly, we need to put the server outside what in larger companies is a significant problem due to internally adopted procedures.
A well-prepared API can be checked by both methods. Polling will show us the quality of the API, and webhooks will check the timeliness and responsiveness of the application.
10 features of a good API
1:. Possibility to search by criteria/date
A well-prepared API must enable searching for data by specified criteria. Depending on the specifics of the API, they can be different.
For example, in our basic real-time Polish National Business Register API, which is used to verify companies, the basic criteria for finding data in the API interface are the identifiers of business entities - identification numbers and a company name. The characteristics of this API is that the user has some economic entity data and what he expects is the current registration data, allowing to check the potential contractor.
If, however, he was interested in the API with company databases, where he would need to analyze companies that were established in 2019, the key criterion would be the date (the option of selecting the registration date range from 01/01/2019 to e.g. 30/07/2019).
2:. API Results Paging
Results paging is an inseparable element of the functional API. Why? The option of limiting the amount of data that can be downloaded at one time, specifying the frequency of requests and notifying how many pages of data we still have to download — it all allows for effective management of large data sets.
Thanks to paging, we are able to determine that, for example, today we want to download only 3 pages of data because that's all we need. Not more.
3:. Requests that really meet your needs
Each API call should have its own Use Case. In other words, handle a specific use case that is met with this single request.
The real value of API isn’t being so divided into small parts, that you need to use more than one request to obtain the data you normally need.
4:. Data sorting
This feature is not obligatory in every API, because it depends on its type. In many cases, Application Programming Interfaces with well-designed requests (see point above!) are enough.
For example, there is no need to sort data using the Polish National Business Register API. Similarly with the weather API. Because what sort there?
But if our API is used, for example, to download 100 million e-books, then sorting will be necessary for us. If we cannot sort the data, i.e. organize them (e.g. by timestamp, title, author), memory paging will be ineffective, because it will not allow us to determine which data we have already downloaded and which data are not and in what order we want to download them.
5:. JSON / REST
Of course, API does not have to be REST to be considered well prepared, but nowadays almost all the clients expect it. REST APIs are simply easier for them. SOAP APIs slowly become a thing of the past.
What is very important, REST supports the JSON format, which is commonly No. 1 among existing formats.
Why JSON?
Of course, the REST APIs support TXT, CSV or XML in addition to JSON (we indicate only the most popular ones here), but JSON remains globally the most universal format - it is lighter than XML, takes up less space and parsing data is here the easiest.
6:. API speed
API is cool if it's fast. After all, when asking about something, we want to receive the answer immediately, not after five days.
There is no single API speed standard, but it should undoubtedly be able to efficiently handle and support multiple queries (if we want to implement the API on 20 computers, it shouldn’t be a problem. Good API should easily do it instead of blocking the responses).
7:. Test environment / API test mode
The test environment or the test mode (API version that has a limited number of requests but allows us to calmly test the API and the real data it provides, without charging any fees before integration) are also very desirable.
We don’t have to explain it, don’t we? It would be nice to play on the stock market in a test environment, without real money, right?
8:. Clear error messages
Frequently underestimated error messages are useful in monitoring API and managing changes. On the one hand, they allow the input data to be validated, and on the other hand, they allow saving information about missing and incomplete data for future optimization.
9:. Authorization via OAuth
Read as a fun oh-autch, open authorization standard (OAuth) helps to share API data with third parties. This secure method of delegating access to server resources is defined during authorization and usually requires the use of tokens. In other words, anyone who receives a token can gain access to data from the server.
OAuth authorization is much more complicated to implement that granting access via an API key, but also significantly increases security.
10:. Reliable technical documentation
Sounds like a cliché, but it's not a cliché. A lot of technical documentation is still written on the knee "for yourself". And it should be written for an external user who does not yet know this particular API.
And what is more, good technical documentation - clearly described and solidly organizing the whole API - is like a manual for IKEA furniture. We will save a lot of time thanks to it.
10 riders of a good API or more?
The above list of 10 features of a good API is not a complete list.
If we asked a thousand programmers what the features of a good API are, we would certainly get a lot of duplicates, but also the same amount (if not more!) of unique answers.
Everyone pays attention to something else. In this case, this is important and in another not. API X rises different expectations than API Y.
For example, we wondered for a while whether we should add the features of good API #11 - libraries. After all, it's extremely convenient to get libraries for various programming languages from the API provider right away. Less time is spent on integration and you can be sure that we use API exactly as its author assumed. Only that the preparation of libraries is very time-consuming and time is money. Most customers do not want to pay extra for libraries. In fact, libraries are only being prepared by giant companies that can afford weeks of work on libraries or by companies that have single box API in thousands of copies and the number of customers justifies the cost.
