As a backend developer who writes APIs from time to time, I’ve always wondered if I am delighting my customers who in most cases are other developers when interacting with my APIs.
Thoughts like these always make me think about lots of things from performance, speed, etc. But very recently I started to think about how the final result of my APIs are formatted and how my supposed customers would prefer to have it. This, most times is not top of mind when writing APIs.
The programming language we use for a particular application usually determines how we structure/format strings. Generally, there are about 4 popular cases for naming things in different programming languages which are:
- Camel case - JavaScript e.g firstName
- Pascal case - Pascal e.g FirstName
- Snake case - Python e.g first_name
- Kebab case - Lisp e.g first-name
So the question is:
what should be the perfect case for the request/response object of my API?
What case do other developers using my API expect to see while interacting with my API?
Should the language I code in be the determinant of how my API request/response object case will be formatted?
These thoughts took me on a journey of API exploration. I don't think there is a better way to get an answer to this question than examining the documentation of some existing brands. Below is what I discovered👇🏼
What I’ve seen so far 👀
Stripe:
Stripe uses snake case for their request/response object across their APIs regardless of the language used. Take a look at their documentation page here
Monnify:
Monnify is a brand of TeamApt, a Fintech company just like Stripe based in Lagos, Nigeria. Monnify uses camel case for the request/response object of their APIs. You can have a look at their documentation here
Twitter
Twitter mostly uses snake case for the request/response object of their API doc at least the parts I’ve worked with. You can also take a sneak peek at their doc here
Eventbrite
Eventbrite just like Stripe uses snake case for their request/response API object. You can take a look at their doc here
Carbon
Carbon API documentation, different from every other one we have looked at uses a mix of snake case and camel case for their request/response object. This is the first time I am seeing anything like this. You can also take a look at their doc here
Conclusion
I must confess that I have seen more JSON-based API request/response object for many documentations in snake_case than any other case but I have also seen a fair share in other cases especially camelCase. I have equally written some endpoints that uses snake case and camel case in various APIs as well but I will also like to have your opinion on this subject.
P.S.
This is a very short article on a very focused topic through which I hope to drive meaningful conversation so do not hesitate to share your opinion on the topic in the comment section below.
Frontend Developers
- As a frontend developer (mobile or web) what case do you expect to consume your API in or what is your most preferred case?
- Do you use any library to convert your request/response object to your preferred case of choice should the API not be in that case?
Backend Developers
- Does the language you write in determine what case your API request-response object will be?
- Do you use any library to unify your API request/response case irrespective of the language? Care to share?
Top comments (9)
The DB schema also has a lot to do with the case of the response data. Most backend devs don’t expressly want to think too much about case of the response, so whatever the database sends, is what the consistency across the project is then based on.
Interesting!
Thanks for your contribution Adedoyin.
snake_case is fundamentally more human readable than camelCase because the words are physically separated. If you don't believe me take a whiteboard, park it outside the office of a senior male colleague and write your_pen_is_small in camelCase on it. You will get into trouble.
I have never really given this much thought but now that you have mentioned it, I think it's better to be consistent with whichever case one eventually chooses.
Definitely, Consistency matters a lot!
Have you seen any API request-response object in Pascal or Kebab case before?
Those are quite rare and I have personally not come across them before or maybe I do not remember.
I have also not seen any API in that case before.
I think the case of the response body should depend on the actual language used. For instance it will be quite odd to use snake case when developing with C# and it will be quite odd to use camel case for a language like python or java
Very important subject that backend devs ignore..nice write up