Introduction

REST (Representational State Transfer) is an architectural style for designing networked applications. It relies on a stateless, client-server communication protocol, usually HTTP. RESTful APIs are widely used due to their simplicity and scalability. This comprehensive cheatsheet covers essential REST API principles and operations, complete with examples presented in HTML tables for easy reference.

1. HTTP Methods

1.1 Basic HTTP Methods

Method Description Example
GET Retrieve information from the server GET /users
POST Submit data to the server POST /users with body { "name": "John" }
PUT Update existing data on the server PUT /users/1 with body { "name": "John" }
DELETE Delete existing data on the server DELETE /users/1
PATCH Partially update existing data on the server PATCH /users/1 with body { "name": "John" }

2. Status Codes

2.1 Common HTTP Status Codes

Code Description Example
200 OK Request succeeded GET /users/1
201 Created Resource created successfully POST /users
204 No Content Request succeeded, but no content to return DELETE /users/1
400 Bad Request Malformed request syntax or invalid data POST /users with invalid JSON
401 Unauthorized Authentication is required Accessing a protected route without valid token
403 Forbidden Client is authenticated but does not have permission Trying to delete a user without admin rights
404 Not Found Requested resource could not be found GET /nonexistentresource
500 Internal Server Error Server encountered an unexpected condition Server-side bug or misconfiguration

3. REST Principles

3.1 Stateless

Principle Description
Stateless Each request from a client to a server must contain all information the server needs to fulfill the request. The server must not store any client context between requests.

3.2 Client-Server

Principle Description
Client-Server The client and server are separate entities that communicate over a network. The server hosts resources, and the client requests them. This separation improves scalability and simplifies component management.

3.3 Cacheable

Principle Description
Cacheable Responses must define themselves as cacheable or non-cacheable to prevent clients from reusing stale or inappropriate data.

4. URL Structure and Endpoints

4.1 URL Components

Component Description Example
Base URL The root URL of the API, typically including the protocol and domain https://api.example.com
Versioning Indicates the version of the API being used, often in the URL path /v1/
Endpoint The path to a specific resource or action in the API /users
Query Parameters Key-value pairs appended to the URL to filter or modify the request ?page=1&limit=10

4.2 Example URL Structure

Component Example
Full URL https://api.example.com/v1/users?page=2&limit=10
Explanation The URL above requests the second page of the user resource, returning 10 users per page.

5. Authentication

5.1 Authentication Methods

Method Description Example
API Key A simple token passed in the request header or query string GET /users?api_key=YOUR_API_KEY
OAuth Standardized protocol for token-based authorization OAuth2 with bearer token: Authorization: Bearer YOUR_ACCESS_TOKEN
Basic Auth Encodes username and password into a base64 token Authorization: Basic base64encoded(username:password)

6. Pagination and Filtering

6.1 Pagination

Term Description Example
Pagination Divides the data into manageable chunks, typically using query parameters like page and limit. GET /users?page=1&limit=20

6.2 Filtering

Term Description Example
Filtering Allows you to narrow down the results based on specific criteria, typically using query parameters. GET /users?age=25&gender=male

7. Versioning

7.1 API Versioning

Method Description Example
URL Versioning Include the version number in the URL path https://api.example.com/v1/users
Header Versioning Specify the version in a custom HTTP header X-API-Version: 1
Accept Header Versioning Use the Accept header to specify the version Accept: application/vnd.example.v1+json

Conclusion

This REST API cheatsheet provides a comprehensive overview of the most commonly used REST API concepts, complete with examples to help you quickly find the information you need. Whether you're building or consuming APIs, this guide serves as a quick reference to help you work more efficiently with REST APIs.