August 19, 2020
During my daily work I often have to deal with APIs, either as a consumer or as a producer of them. I have created APIs, some more RESTful than others and I have made a lot of mistakes. Fortunately, there are many guides on-line on how to create a “true” RESTful API. I particularly like this one. However, I think most of these guides miss one important aspect, and that is the eventual objective of the API. If anything, the API is there to provide users with access to useful data.
Can’t see the forest for the trees
Developers focus a lot on standards and definitions. I get it, especially in large projects where many people are involved in coding for it. However, you can have a near-to-perfect design of your API, if the data you can get out of it as a user is unclear, sloppily defined or plain unusable, the API is worthless. Most will say, well isn’t that part of your design process? And, I would agree, but most of the guidelines for building an API seem to focus on the method and less on the outcome.
My APIs might not always be exactly RESTful, but I do try to focus on the data that a user can get out of them. Below are a couple of examples I have encountered in real life, which I now try hard to avoid. I am no expert on APIs and for many these examples might seem obvious, but I’ve encountered enough of them to get a bit (just a bit) worked up over them.
What does v stand for
Resource attributes in an API should be self-explanatory. If an API needs 20 pages of documentation to explain that
value and not
velocity or that p_id means
parent_id and not
project_id, I will have to spend more time on understanding the data than on actually using that data for something worthwhile. As a consumer of your API, I don’t care what you call your attributes in the database, heck if you’re happy with
p_id, that’s fine by me. But, once you make that data available to the public through an API, please be so kind to add the
AS value and
AS parent_id to your SQL query.
Normalize your database, don’t normalize your output
Normalizing the data in your relational database is good practice. Again, I get it, but I’ve encountered APIs where the normalization was applied to the resources as well. To give an invented example based on reality: I could get a list of students, I could get a list of classes, but to figure out which students were taking which classes, I had to make a separate call to a different endpoint to get the intermediary table, which was filled with:
c_id. This means, I don’t just have to figure out what those names mean, I also have to somehow join multiple resources on the client side. I always understood that relational databases were build to make those joins efficiently. I am pretty sure that they will always do a better job than me looping over classes and students to find possible joins. Please, but pretty please, make the data your API throws out useful for me. If that means that your backend code has to do some more work, just do it, it will make me want to use your API instead of cursing the person who developed it.
Give me the data, but don’t give me all of it
Many of the APIs I’ve worked with were very specifically developed for a particular sector. This could range from students and classes, to economic data, to inventory management systems. For many of them I would often get a neat
Just a friendly piece of advice
Like I mentioned before, I don’t consider myself an expert on designing APIs. I also make many mistakes, and will make many more, so I am not trying to bash developers here. However, I do know what APIs are used for. By all means, follow all the guidelines for creating a RESTful API, but in the end make sure that what your API spits out is useful, even for people who don’t necessarily have a very technical background.