Table of Contents
Learn how to create APIs.
In the world of REST APIs, one endpoint can perform multiple tasks. It can deliver a resource, create a new resource, update or delete it. The endpoint remains the same while the action varies. When a client invokes an API, how does the API developer know which of the multiple actions should be performed? This is where HTTP methods come in.
HTTP methods or request types tell the API endpoint what it should do with the resources. It defines the action. The API developer makes decisions and manipulates resources appropriately based on the HTTP methods in an HTTP request. Here is a list of the most used HTTP methods and which action you should initiate for those calls.
| HTTP method | Action |
|---|---|
| GET | Returns the requested resource. If not found, returns a 404 Not Found status code. |
| POST | Creates a record. The POST request always comes with an HTTP request body containing JSON or Form URL encoded data, which is also called a payload. If the data is valid, the API endpoint will create a new resource based on these data. Although you can create multiple resources with a single POST call, it is not considered a best practice to do so. |
| PUT | Instructs the API to replace a resource. Like a POST request, the PUT request also comes with data. A PUT request usually supplies all data for a particular resource so that the API developer can fully replace that resource with the provided data. A PUT request deals with a single resource. |
| PATCH | Tells the API to update a part of the resource. Note the difference between a PUT and a PATCH call. A PUT call replaces the complete resource, while the PATCH call only updates some parts. A PATCH request also deals with a single record. |
| DELETE | Instructs the API to delete a resource. |
Rule 1: Everything in lowercase, with hyphens and not abridged
✅ /student-records
❌ /StudentRec
Rule 2: Use a forward slash to indicate a hierarchical relationship
✅ /schools/123/students/456
❌ /schools?id=123&student=456
Rule 3: Use nouns for resource names, not verbs
✅ /books
❌ /getBooks
Rule 4: Avoid special characters
✅ /user-profiles
❌ /user@profiles
Rule 5: Avoid file extensions in URI