How to design better APIs

Hey LE Xie! I love that you're considering translating my article into Chinese – I'd be more than happy. ❤️‍🔥 Please just make sure to attribute my original article and link back to my blog. Let me know once you publish it – looking really forward. :)

Thank you for your permission! Of course, your blog and original article will be put into Chinese translations. Here is the article url. mp.weixin.qq.com/s/v6BO_E8e-oJRazuYEEpksA

LE Xie awesome, thanks so much for translating the post! 🥳

Thank you for your feedback Christos Matskas!

I'm not sure if I agree whether expanding resources can lead to security issues. It's typically a responsibility of the API not to disclose any sensitive information from the database. If you're not transferring database objects directly (which you probably shouldn't), I don't see a big problem.

What do you think?

Thank you Annie 🦄⚡! I'm glad you found this post useful. 🙂

Thanks Ezequiel E. Tejada! Happy to help. 🤗

Thank you Ronald. PS: Great name! 😉

Thank you for your kind words, Yannick. 🤗

Thank you so much, Jackson Lee! 🤗 I appreciate the kind words and I'm happy you could use some of the tips for your project. If you have any questions, just let me know.

Thank you Rohan Ankarigari Boda. You are right, OData already covers some of these. Although I have a feeling that OData never really got to the point where it would make sense for me to support it.

Have you ever implemented OData?

Ronald Blüthl Yes, I have implemented OData APIs as part of my work on Microsoft’s Graph API. The Microsoft Graph API platform is perhaps the largest OData based set of APIs.

The biggest challenge I faced was implementing OData APIs for data and contracts which didn’t exactly fit into the OData way of things. Another challenge was the fact that the OData libs are not ready for a microservices world (IMO) where data resides in some service and data is surfaced by another service.

In my personal projects I have been lucky not to use OData.

Hey Simon Espigolé, happy you liked my post. I'm not familiar with Spring Boot, but the principle is usually the same. If you're using an OR mapper (such as Prisma for example), you can "include" or "expand" related entities and load them from the database in one go.

The flow would roughly look like this:

• API accepts an expand parameter for GET requests
• The expand parameter is interpreted and passed to the OR mapper
• Entities are loaded from the database and passed back as response

Check out the Prisma documentation for more details: prisma.io/docs/concepts/components/prisma-…

If you have any questions, just let me know.

Thanks for your answser Ronald Blüthl. I'm familiar with the concept of resource expansion and how to do it but I'm struggling with the implementation with Spring Boot/Hibernate, especially with lazy-loaded entities (where I only want to join the tables that the client has requested via ?expand=).

Anyway, thanks for the link to Prisma, I didn't know this ORM. Have a nice day !

Glad you liked it, Xuan Nguyen! Thanks for reading. :)

Thanks for your feedback, Robert!

Versioning could be a separate topic in itself I guess. As aways, there are many approaches I'd say. :)

That's awesome to hear, Saikat! Glad you enjoyed the post.

Happy to help, Chinwendu. :) Thanks for your valuable feedback, I appreciate it.

Thank you very much, Héctor!

Thank you, Afdallah! 🥳 I‘m thinking about putting together a reference implementation myself, but in the meantime I recommend you to look at Stripe‘s API, which is probably the best one I‘ve worked with: stripe.com/docs/api

Hope this helps! ✌️

Love to hear that the post was helpful to you, Aisha! ✌️

It‘s so nice to hear that you can benefit from my article, Ilyas! 🙂 All the best to you, and if you have any questions just let me know. ✌️

I totally agree. It's the most important part - that's why it's #1. :) Thanks for your kind words!

Hey Jamarob! I'm happy you liked the post - thank you. 😎

You could definitely do that - I think there's no "convention" here, just best practices.

What I usually do is use the "Authorization: Bearer {token}" format when passing JWT tokens, but use the "Api-Key: {apiKey}" format when passing API keys. It's more like a matter of taste I guess.

Hey abdolrahman kiany!

Thanks for your question. POST doesn‘t necessarily imply that the endpoint needs to return something. It merely implies that something is written or changed instead of read.

So in your case (following a user) I‘d go with something like.

POST /users/{id}/follow

• POST because something is WRITTEN (e.g. following a user, which triggers a change in your database)
• {id} of the user that is subject to be followed
• And then follow to explicitly specify the action

Of course it depends a bit on your current structure, but something along those lines should work just fine.

Hope that helps – reach out to me via Twitter (@rbluethl) if you need any more help.

Ronald Blüthl Hi, I am not the author of the original comment, but I wanted to comment on your answer. With the REST API, is it good practice to include verbs such as "follow" in the endpoint names? My point is that the REST API is all about resources, and "follow" is not a resource. Or am I being too strict about this and should be more pragmatic?

Hi MPatchesny!

I think it's mostly a matter of taste, but as for myself, I'm not too strict in that regard. What's more important is to use the correct HTTP verbs (POST for creating, PATCH for partial updates) and so on. If you look at big/popular public APIs (such as GitHub or Slack), you can see that they don't strictly operate on a resource-level either. Just make sure your endpoints speak for themselves and are easy to follow/make sense.

Hope that helps & thanks for reading in the first place. :)