Must Know Concepts About Designing APIs

Hello coders, I am back with a fully detailed article today. Designing APIs could be a pain in the ass if you don’t have a plan. Designing APIs is, in my opinion, one of the most important steps in building a product. If you create your APIs up to the standards, you will be able to find and solve bugs quite easily.

I am going to talk you through from the basic explanation of what an API is to all the things I find important that are not being discussed often.

What is an API?

API stands for Application Programming Interface. According to Webopedia,

An application program interface (API) is a set of routinesprotocols, and tools for building software applications. Basically, an API specifies how software components should interact. Additionally, APIs are used when programming graphical user interface (GUI) components. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together.


I know you didn’t understand a word. Let me break it down with a simple example.

When you write a comment for a post on Facebook and press Enter, Facebook sends a request to its remote server and the server will send a response back accordingly. The part of the remote server that accepts the request and sends the response is called an API.

Adding APIs to a System

1. Adding to an existing system

This is the fastest way to get it going. Since we already have a working system underneath, we just have to analyze the code and the logic and design the API.

The main drawback here is that we might have to face unexpected problems due to errors made in the initial building process of the existing system.

2. Building from the scratch

We are less likely to face unexpected errors since we design the whole thing from scratch. Developers can utilize the latest technologies and architectures in building the system.

The drawback visible here would be that it could take a long time to get the system up and running

3. Replacing piece by piece

Most of the developers prefer this strategy since the customer has a working system to work with and in the meanwhile, the developer can develop his part of the system.

Most Popular HTTP Methods

1. GET

This should only be used to retrieve a collection of resources (or a resource)


Used to delete a resource

3. PUT

Updates an existing resource


Can be used to create new resources or modify them.

Matching Verbs with HTTP Methods

Let’s think we are building an online shopping store. Here is how you could use the HTTP Methods according to the activities.

Viewing or listing an item(s), Viewing orders can be done using a GET request.

Checking out an item, Creating the cart, Cancelling orders can be done using a POST request.

Adding items to the cart can be done using a PUT request since we’ve already created the cart.

Deleting or Clearing an item(s) can be done using DELETE requests.

Types of Relationships between Resources

1. Independent

Can exist on its own without other resources. For example, an item can exist on its own.

2. Dependent

Can only existing if another certain resource exists. For example, an order can’t exist without a cart

3. Associative

Can’t exactly say whether it is independent or dependent by just looking at it. For example, a role in a movie might be played by many actors and the same actor might act different roles at different times.

The Most Important Step in API Modeling

When you are designing an API, the first and the most important thing you need to do is to choose a medium that you would use to document your process. This could be a pen and paper or a document online. You can’t switch the medium while you are in between the process. So, choose what works for you.

This document should include all of your assumptions, decisions, tasks, the gaps you might have to take a look at later and anything else that might be important for you and your team.

You can share this document among your team members so that if a customer asks about a certain decision that has been made, your team could answer confidently.

HTTP Response Codes and Their Meanings

1. 1XX Series (Informational)

You are unlikely to see these errors. These errors are informational.

2. 2XX Series (Success)

2XX codes mean the request was successful. Here are all the 2XX codes with their meaning

  • 200 – OK
  • 201 – Resource has been successfully created
  • 202 – The performed action is underway, but not complete yet
  • 204 – No content (Usually when a requested resource was deleted)
3. 3XX Series (Redirecting)

3XX codes are received when a resource has been moved from its original URL

  • 301 – Moved Permanently (The requested resource is no longer available in the given URL)
  • 302 – Moved Temporarily ( Even though the resource is no longer available now. It has a chance of reappearing)
4. 4XX Series (Client Error)

4XX codes are errors made by the client who is making the request.

  • 400 – Bad Request (The request failed to an error of client)
  • 401 – Authentication Required
  • 403 – Forbidden (Request was correct and was authenticated, but failed)
  • 404 – Not Found (The requested resource does not exist. It was not deleted or moved. It simply does not exist)
5. 5XX Series (Server-Side Errors)

These errors are from the server-side. As a developer, you can’t do anything about them

And another thing I’ve learned from listening to coding experts is that we should always try to stick to these standard response codes and not create our own. These codes have been standardized for a reason.

Thank you for reading my article. I hope you learned something valuable from it. If you did, drop a like and follow my blog to get notifications when I publish new articles. I write articles about coding, cricket and things that I find interesting. I try to publish articles every other day.
Have a nice day ✌

Published by Thisura Thenuka

I am a passionate software engineering student. But cricket is my first love ❤

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: