Updated: Sep 4
We’re almost done learning the basic concepts we need to understand APIs better.
Let’s recap what we have learned so far:
Understanding APIs (Part 1): What is an API? - We defined the initial diagram.
Understanding APIs (Part 2): API Analogies and Examples - We talked about the Restaurant and Calculator analogies and defined the Human Resources API example.
Understanding APIs (Part 3): What are HTTP Methods? - We learned the 5 most popular HTTP methods: GET, POST, PUT, PATCH, and DELETE.
Understanding APIs (Part 4): What is a URI? - We learned that a URL is just a form of URI. We broke down a URI into protocol, host, and path.
Understanding APIs (Part 5): Intro to Postman and Query Parameters - We learned how to use Postman and what Query Parameters are.
The last 3 posts mentioned components sent in the Request that tell the API what data we want to receive. This time, we’ll be talking about a part of the Response: the HTTP Status Codes.
What are HTTP Status Codes?
HTTP Status Codes are numbers returned by the API which are included in the Response. They indicate if the operation you wanted to perform was a success or not, and they describe the kind of success/failure that happened. It’s basically a conversation with the server where it tells you, “here is the data you requested,” “your Request is not correct; please take a look,” “I’m having internet issues; please try again later.”
There are a lot of Status Codes reserved for certain API Responses, but we will be looking at the most popular ones: 200, 201, 202, 204, 400, 401, 403, 404, and 500. You can find a complete list here with their definitions.
Note: Any developer, API designer, or architect can choose the status codes they want the API to return. Some APIs only return 200, while others only return 200, 400, and 500. However, I will follow the best practices shown by REST API Tutorial.
This code is returned when the Request is a success, and there are no errors whatsoever. It’s mainly returned when using a GET or a POST. The Response will contain the data requested by the GET or the data created/updated by the POST.
This code means that the Request is a success and that a new resource was created. For example, a new employee was added to the company list successfully. The Response usually contains the data that was just created. It’s mainly returned when using a POST or a PUT.
This code is returned when some processing is still pending, but it hasn’t been completed yet. This code is especially useful when the back-end processing of the information will take too long to complete, so the user receives a confirmation of the Request along with a pointer to monitor the processing status. Note that this doesn’t mean that the Request was a success. It just means that the server received it, but it can still fail its processing.
204 No Content
This code means that the Request is a success, but there is no data to be returned. For example, when deleting a resource, nothing is returned because it no longer exists. It’s mainly returned when using DELETE.
400 Bad Request
The Request contains a syntax error that could not be understood by the server. For example, if your Request needs to have a field called “FullName” and you don’t send it to the API, it will return this error.