REST API Cheatsheet

Table of Contents

1. Introduction to REST
2. HTTP Methods
3. Status Codes
4. URI Design
5. Request Headers
6. Response Headers
7. Content Types
8. Authentication
9. HATEOAS
10. Versioning
11. Caching
12. Best Practices
13. Tools

Introduction to REST

REST (Representational State Transfer) is an architectural style for designing networked applications. It relies on a stateless, client-server communication protocol, typically HTTP.

Key principles:

• Client-Server architecture
• Statelessness
• Cacheability
• Uniform Interface
• Layered System
• Code on Demand (optional)

HTTP Methods

GET     : Retrieve a resource
POST    : Create a new resource
PUT     : Update an existing resource (full update)
PATCH   : Partially update an existing resource
DELETE  : Remove a resource
HEAD    : Similar to GET but without the response body
OPTIONS : Describe the communication options for the target resource

Status Codes

1xx : Informational
2xx : Success
3xx : Redirection
4xx : Client Error
5xx : Server Error

Common codes:
200 OK                  : Request succeeded
201 Created             : New resource created
204 No Content          : Request succeeded, no content returned
400 Bad Request         : Invalid request
401 Unauthorized        : Authentication required
403 Forbidden           : Server understood but refuses to authorize
404 Not Found           : Resource not found
405 Method Not Allowed  : HTTP method not supported for this resource
500 Internal Server Error: Generic server error

URI Design

https://api.example.com/v1/resources/{id}

- Use nouns, not verbs
- Use plural nouns for collections
- Use hyphens (-) to improve readability
- Use lowercase letters
- Don't include file extensions

Examples:
GET     /users          : List all users
GET     /users/123      : Get user with ID 123
POST    /users          : Create a new user
PUT     /users/123      : Update user 123
DELETE  /users/123      : Delete user 123
GET     /users/123/orders : Get orders for user 123

Request Headers

Accept          : Specify desired content type
Authorization   : Provide authentication credentials
Content-Type    : Specify the media type of the request body
User-Agent      : Identify the client application
Cache-Control   : Specify caching directives

Response Headers

Content-Type    : Specify the media type of the response body
Cache-Control   : Specify caching directives
ETag            : Provide a version identifier for the resource
Location        : Specify the URL of a newly created resource

Content Types

Common MIME types:

application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain

Authentication

Common authentication methods:

Basic Authentication:
Authorization: Basic base64(username:password)

Bearer Token:
Authorization: Bearer <token>

API Key:
X-API-Key: <api_key>

OAuth 2.0:
Authorization: Bearer <access_token>

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of REST application architecture.

Example JSON response with HATEOAS:

{
  "id": 123,
  "name": "John Doe",
  "links": [
    {
      "rel": "self",
      "href": "https://api.example.com/users/123"
    },
    {
      "rel": "orders",
      "href": "https://api.example.com/users/123/orders"
    }
  ]
}

Versioning

Common versioning strategies:

URI Versioning:
https://api.example.com/v1/users

Header Versioning:
Accept: application/vnd.example.v1+json

Query Parameter Versioning:
https://api.example.com/users?version=1

Content Type Versioning:
Content-Type: application/vnd.example.v1+json

Caching

Cache-Control header directives:

Cache-Control: max-age=3600
Cache-Control: no-cache
Cache-Control: no-store
Cache-Control: private
Cache-Control: public

ETag usage:

Response:
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Subsequent Request:
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Best Practices

1. Use HTTPS
2. Version your API
3. Use plural nouns for resource collections
4. Provide comprehensive documentation
5. Implement proper error handling with descriptive messages
6. Use pagination for large data sets
7. Support filtering, sorting, and searching
8. Implement rate limiting
9. Use appropriate HTTP status codes
10. Make your API stateless
11. Implement HATEOAS for discoverability
12. Use JSON as the default data format
13. Implement proper authentication and authorization
14. Use caching mechanisms
15. Provide a way to batch API calls

Tools

1. Postman - API development and testing
2. Swagger - API documentation and design
3. cURL - Command-line tool for making HTTP requests
4. JSONLint - JSON validator
5. JSON Editor Online - JSON editor and formatter
6. Insomnia - REST client
7. Apache JMeter - Load testing and performance measurement
8. Charles Proxy - HTTP proxy for debugging
9. Fiddler - Web debugging proxy
10. REST-assured - Java DSL for testing and validating REST services