REST API Cheatsheet: Comprehensive Guide with Examples
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.
Comments
Please log in to leave a comment.