Let’s Make a Standard API
What is the best way to design a standard API? What exactly do good APIs have? According to Brenda Jin, Saurabh Sahni & Amir Shevat in their book Designing, Web API’s quality of an API is measured by:
1. Usability
2. Scalability
3. Performance
USABILITY
A good API should be simple to use. But what exactly defines simplicity. Simplicity depends on context, but there are guidelines we can follow.
Design the API with the knowledge of the developers that will use it.
Make it fast and easy to get started with the API
Design comprehensive and detailed documentation for the API. (If possible, make it interactive)
Design a developer ecosystem around the API.
SCALABILITY
The requirements customers are likely to change in the future. In the event of a change, APIs need to meet up. Scalable APIs should be designed for expansion or reduction as the market for the API evolves.
GitHub is a good example. GitHub started as an online repository for static files. With time they have added several other features to the application. Codespaces, continuous deployment, collaboration are some favorites amongst others.
PERFORMANCE
Perhaps this is one area where developers may feel is the most important. Performance cannot be stressed enough in any application.
Imagine a scenario; Mario’s startup uses machine learning to deal with traffic congestion in certain hotspot regions in his city. His solution reduces traffic congestion by 35% in his test environment. Mario does not run enough end-to-end tests, but rather with the end-to-end tests, he deploys the solution to production as an API. Using machine learning to solve traffic congestion issues sounds fine, but implementing it in production shows a bottleneck in processing time. Running the application in real-time is inefficient because a lot of time will be used between the video transmission and the result given back. Also, the documentation available is not very helpful. Getting the application to work is as hard as getting a degree in applied mathematics.
David develops another API to handle traffic congestion in the same city as Mario. He plans to succeed where Mario failed. He uses a similar algorithm to Mario, but he reduces the load on the network by allowing processing to be done on some abstract levels to speed up performance. David also develops comprehensive interactive documentation, making it easier for developers to use his API. He believes the future is bright, he has plans to grow with the market, maybe handle routing or controlling traffic on a city level rather than one traffic post at a time, or clients will be abundant for his API. He builds his program with that on his mindset, making sure the application is scalable.
I know my writing may have been a bit biased, but who do you think will do better in the long run. One question:
How simple is it to design an API based on the guidelines above? Why don’t we experiment with a potential problem?
“Ever since the introduction of Computer Based Test to JAMB Matriculation tests, the results have been undulated.CBT has benefits like reduction in examination malpractice, the faster culmination of results, and a more organized examination process are some advantages noticed. Surprisingly the success rate has not increased but reduced.
The pass mark allowed by JAMB to get admissions into universities in Nigeria is 160. The pass mark accommodates students below the previous cutoff mark of 200. Many applicants are not given admission into University. The reason may be while they beat the cutoff mark, they do not meet the score required by their institution of choice. Which leaves them the option of going for a different course or going to a smaller institution like a Polytechnic.
How many students fail or have to settle for something else?. In 2018 only 25.09% of candidates scored above 200. In 2019 23.83% scored above 200. In 2020 and 2021, 31.97% and 12.84% of candidates scored above 200 respectively.”
Get Real-life Developer Requirements
While data provided by APIs are for end-users, APIs should be for software developers who integrate the API with their applications. Knowledge of the developers using this platform is necessary, so we need to get the requirements from the potential developers that will consume this API.
Technology Selection
For APIs, there are various programs and implementations we can use. With the developer requirements, now we decide on the technology stack to produce the best result. Here we select the type of API to use, the security measures to be put in place, even the language that will all be selected here.
Something to note here, at every point in development, the solution should be geared towards the requirements of this application, not towards some pre-bias towards certain technologies; you are welcome to critique any step I take.
Design the application
Here we decide the structure our data is going to take. With knowledge of all the features needed, we design a model for our database, modules, etc.
It’s as simple as that.
Implementation of Design
Now the fun part. With the research we have, we build the solution. We finally code.
We’ll walk through every piece of code and implementation as we code.
Testing
No matter how great a solution can be, it will lose users if it does not work. We run tests to be sure our software is effective.
Documentation and Validation
We release the API to the public with documentation and see how it performs outside of a test environment.
Now, this will not take a week but longer. If you have observations or suggestions do let me know, and join me on this ride. I believe it will be fun.