A REST API is a type of API that confirms to the RESTful constraints. REST is designed to take advantage of existing protocols like HTTP.

It’s very important that our API has a Uniform Interface which means communication is simple and predictable. For an API to be simple and predictable we should use standard HTTP Status Codes and HTTP Request Methods.

As you will see in this article, a well designed RESTful API will take advantage of HTTP Status Codes and HTTP methods like GET, PUT, POST, and DELETE.

HTTP Status Codes

An HTTP Status Code is returned by the server in response to a client’s request. The status codes are three digit codes.

The first digit of the HTTP Status code is a number between 1 to 5 that indicate whether it’s successful, redirected, client errors, or if the server is having problems.

1. 1xx- Informational Request. I have never seen this range used.
2. 2xx- Request was successful.
3. 3xx- Request was Redirected. Pretty much never use this when building an API. I use it for SEO redirects on websites.
4. 4xx- Client Errors (often codes like 404 – page not found)
5. 5xx- Server problem (most often 500 when is an Internal Server error).

I can’t remember the last time I seen a 100-199 status code. I don’t think they’re normally used. 200, 201, 202 are the normal status codes.

HTTP Status Code 200

• Stands for “Okay”
• Usually sent in response to GET, POST, PUT, and DELETE. I don’t personally agree with it being used for POST or DELETE but it’s regularly used for it.

HTTP Status Code 201

• Stands for “Created”
• Should be sent in response to POST.

HTTP Status Code 202

• Stands for “Accepted”.
• Should be used when the request hasn’t been completed yet. I don’t think I’ve ever seen it used.

HTTP Status Code 203

• Normally used for caching when the data isn’t the same as the origin server.

HTTP Status Code 204

• Means the body has no content.
• I usually use HTTP Status Code 204 for DELETE.

HTTP Status Code 3xx

• Shouldn’t normally be used in API development

HTTP Status Code 400

• Bad request
• Something is missing if it’s a POST or PUT.

HTTP Status Code 401

• Unauthorized / Invalid Token or API Key

HTTP Status Code 402

• Payment required. Don’t think I’ve ever seen this implemented.

HTTP Status Code 403

• Unauthorized – you don’t have access to this.

HTTP Status Code 404

• Not found – the resource is missing.

HTTP Status Code 405

• Method not allowed.
• Sometimes used when DELETE isn’t allowed on a certain resource.

HTTP Status Code 422

• Unprocessable entity
• Usually used when the request is missing parameters or invalid (ie something is null when it should have a value)

HTTP Status Code 429

• “Too many requests”
• I usually use this when doing rate limiting.

HTTP Status Code 500

• Internal server error.
• Usually the result of bad code or something unexpected happening.

HTTP Methods

The HTTP verbs or HTTP Methods are the one of the most important parts of the “uniform interface” constraint. They allow us to provide an action with the noun based resource. POST, GET, PUT, PATCH and DELETE are the most frequently used verbs. The verbs clearly align with CRUD operations. OPTIONS and HEAD are other verbs you may see used frequently.

• GET to retrieve a resource;
• PUT to change the state of or update a resource, which can be an object, file or block;
• POST to create that resource; and
• PATCH – update/modify
• DELETE to remove it.

VERB	CRUD Operation	Standard Return Codes
GET	READ	200, 401, 403, 404
POST	CREATE	200 (should be 201), 201, 401, 403, 404,422
PUT	UPDATE/UPSERT	200, 401, 403, 404,422
PATCH	UPDATE	200,401,403,404,422
DELETE	DELETE	204,401,403,404,422

GET Method

GET methods should be used to read a resource. The response code used should be 200 (OK) with it in json, xml, or some other format in the body. The HTTP specification advises that GET requests shouldn’t change data. So, it’s safe and won’t result in data modification or corruption.

POST Method

The POST verb should be used to create new resources. When creating a new resource, we should POST to the parent and the service takes care of creating the new resource and assigning Ids and resource URIs. When successful it should return an HTTP status code of 201 and return a Location header with a link to the new URI.

POST calls aren’t idempotent meaning that every call to the endpoint could result in a new resource being created with the same information.

PUT Method

The PUT method should normally be utilized for update capabilities. The way a PUT should work is updating the resource entirely instead of updating just the properties being passed in. I like to use a 200 http status code for successful updates.

Some people will use PUT to also do database inserts or upserts. I don’t generally do this because I find it to be confusing.

PUT calls aren’t necessarily idempotent meaning every call to the endpoint could result in updated happening multiple times.

PATCH Method

PATCH requests should only contain changes to the resource. Anything in the body should be updated.

PATCH requests aren’t idempotent.

DELETE Method

DELETE is very self explanatory, anything sent as a delete to specific URI should be assumed to be delete. A 204 status or 200 status should be considered successful.

Calling delete a second time on a uri should result in a 404 error because it’s been removed.

Wrapping It Up

In this article, we’ve discussed HTTP Status Codes and HTTP Methods. These are the building blocks of building a useful remote RESTful API.