Photo by Bench Accounting on Unsplash

How to design clean API interfaces

This is going to be a tough read. This contains too much code to read and no pictures. It’s not for people with faint hearts. So read if you are ready to get bored and learn something new.

When you’re designing an API you want it to be consumable. Think of each consumer as a customer and your API as a product. You don’t want to make yourself happy, you want your customers to be happy. Design it in a way that is easy to consume. Performance is a factor but don’t overlook ease of use.

I can’t even count how many APIs I’ve written so far, but I surely have written a lot of bad ones. Based on those This blog post will mention some pointers to remember while developing a good and clean API.

Let’s understand modification Vs extension

That sounds like a very cliche term. Let’s break it down further. Let’s say you have an endpoint that gives you the items in the user’s cart. The response type of the API will look something like the following

{
  "cart": [
    {
      "itemId": "babbf56f-3eea-4fe6-9601-159f8c78f056",
      "item": {
        "name": "Macbook Pro 14inch",
        "listedPrice": 34000000
      }
    }
  ]
}

Now if the manager tells you that products do not have “name” but “title” instead, if you change the name key to title…