Top 5 Things To Be Careful About API design and Development

Bora Erbaşoğlu
Oct 1, 2017 · 2 min read

First of all, you need to consider what is your API’s scope. Who you gonna serve your service. For example, sustainability will force you to write full documentation. Let’s mention some important details.


If you want to enlarge your business exact way then you have to improve your documentation step by step. End of the day, you must apply all changes within your code to your document. If you don’t, things will cause confusion in the future.

Stability and Consistency

If you are developing a web service which serving public users, then you have to pay attention to build your service routes depending on your roadmap versions. For example, if you published version your API route has to be like “/api/V2/get-users” or “/api/V2/get-users?version=2”. It depends on your service methods. I suggest you use SEO friendly version because of it is more memorable.


Some of the cases need to serve service response multiple types. Not every platform has very good JSON support, a decent OAuth library, etc.). In this case, your architecture must have a flexible structure. You could allow this to also be specified in the URL (e.g., /api/v1/get-users.json), or you might also read and recognize an Accept: application/json HTTP header, or support a “query string” variable such as ?format=JSON, on getting methods and so on.


If you choose a secure token method, you have to ensure you are not using a short numeric identifier. For example, it’s relatively simple to just generate out an “SHA” token during user creation and store it in the database. Then, you can simply and uniquely query your database for any users matching that token. You could also generate a token with a unique identifier and a salt value, something like SHA(User.ID + “YOUR SECRET” + now()), and then query for any user that matches; e.g., where TokenFromPost = SHA(User.ID + “YOUR SECRET” + now()).

Another very good option is OAuth 2 + SSL. You must be using “SSL” anyway, but OAuth 2 is reasonably simple to implement on the server side, and libraries are available for many common programming languages such as PHP, Python, Ruby, Java etc.

You need to know where to choose parallel process-based or thread-based architecture

If you really need to serve API which contains complicated algorithms which needs powerful computing then you have to ensure you are using parallel processing and at least working on two core CPU. Otherwise, if you are working on file system process or something like that you have to work on thread bases architecture.

Thanks for reading

Bora Erbaşoğlu

Written by

Technical Software Development Manager

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade