REST API Fundamentals: From HTTP Methods to Status Codes and Beyond

REST API (Representational State Transfer) is an architectural style for designing networked applications. It uses HTTP to perform CRUD (Create, Read, Update, and Delete) operations on resources, which are usually represented as JSON or XML objects.

Also Read: What is an API?

Fundamentals of REST API

1. Resources and URIs:

REST APIs use Uniform Resource Identifiers (URIs) to identify and access resources. For example, a blog API could have the following URIs:

/posts (represents all blog posts)

/posts/1 (represents a specific post with ID 1)

Also Read: Standard Laravel Responses

Request Anatomy

• URL: URL means Uniform resource locator, which is the address to not just justify a resource, but also to specify how to access it. In an API, the URL can be named as base URL, which means that is the base address that will be used in every request. 
  For example: https://api.twt.com
• URI: URI means Uniform Resource Identifier, which is used in the URL to specify which resource the Client would like to access in a request. For Example: https://api.twt.com/feed?type=posts&published=true

we add the ? in URL, followed by item which we want to search 
Here the client communicates to the server that the request is to retrieve products with type equals posts and published equals true.

URI Example: https://api.twt.com/posts

Here the URL is: https://api.twt.com

and URI is: /posts

Therefore, every URL is an URI, but not all URIs are URLs.

• Body Params: It's the body of the request which contains all the data that the server needs to successfully process the request. Therefore, its only used in requests that send information, such as create or update.

For Example:

{
"category": "web",
"published":true,
"no_of_posts":10
}

• Parameters: Parameters are information that can be sent in a request by the client in order to influence the response by the server.  
  There're two types of parameters.
  • Path Parameter: 
    It is a variable in URI path that helps in pointing towards specific resource: 
    For instance, https://api.twt.com/posts/category/web, here web could be the path parameter that is a variable and could be anything, so this API responds with all posts in web category.
  • Query Parameter: 
    It is variable in URI path that helps in querying/filtering through a list of resources.
• Headers: Headers allows sending extra information in a request, such as authentication tokens and content types, for example:

Also Read: Rest API in PHP

For example:

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json

In the above example, the client is sending headers to request response in desired format and passing in authorization token to get the results.

2. HTTP Methods:

RESTful APIs use standard HTTP methods to perform operations on resources:

GET: Retrieve a resource or a collection of resources. For example, GET /posts retrieves all blog posts, while GET /posts/1 retrieves the post with ID 1.

POST: Create a new resource. For example, POST /posts with a JSON payload creates a new blog post.

PUT or PATCH: Update an existing resource. For example, PUT /posts/1 or PATCH /posts/1 with a JSON payload updates the blog post with ID 1.

DELETE: Remove a resource. For example, DELETE /posts/1 deletes the blog post with ID 1.

3. Statelessness:

REST APIs are stateless, meaning that each request must contain all necessary information for the server to process it. Servers don't store any information about the client's state between requests.

4. Cacheability:

RESTful APIs can leverage caching to improve performance by storing a copy of a previously retrieved resource and using it for subsequent requests, reducing server load.

5. Content Negotiation:

Clients and servers can negotiate the format of the data exchanged, typically using the Accept and Content-Type headers. Common formats are JSON and XML.

Status codes

HTTP status codes are three-digit numbers that indicate the outcome of an HTTP request. They help clients understand if the request was successful or if any issues occurred during the processing. Status codes are grouped into five classes based on the first digit:

1. 1xx (Informational): The request was received, and the server is continuing to process it.
2. 2xx (Successful): The request was successfully received, understood, and accepted.
3. 3xx (Redirection): Further action needs to be taken to complete the request, such as following a redirect.
4. 4xx (Client Error): The request contains bad syntax or cannot be fulfilled by the server.
5. 5xx (Server Error): The server failed to fulfil a valid request.

Also Read: Handle CORS errors

Here are some common status codes used in REST APIs:

• 200 OK: The request was successful, and the server has returned the requested data.
• 201 Created: The request was successful, and the server has created a new resource as a result.
• 204 No Content: The request was successful, but there's no data to return (common for DELETE requests).
• 400 Bad Request: The client's request is malformed or contains invalid data.
• 401 Unauthorized: The client needs to authenticate to access the requested resource.
• 403 Forbidden: The client does not have the necessary permissions to access the requested resource.
• 404 Not Found: The requested resource could not be found on the server.
• 405 Method Not Allowed: The client has used an HTTP method that the server does not support for the requested resource.
• 409 Conflict: The request could not be completed due to a conflict with the current state of the resource (e.g., updating a resource with outdated data).
• 500 Internal Server Error: The server encountered an error while processing the request.

Also Read: Build API with Laravel

These status codes help REST API clients handle responses more effectively by understanding the outcome of their requests and taking appropriate actions based on the status codes received.