REST API Cheat Sheet

HTTP Methods

The nine standard HTTP methods define the action to perform on a resource.

Method	Purpose	Request Body	Idempotent	Safe
GET	Retrieve a resource or collection	No	Yes	Yes
POST	Create a new resource	Yes	No	No
PUT	Replace a resource entirely	Yes	Yes	No
PATCH	Partially update a resource	Yes	No*	No
DELETE	Remove a resource	Optional	Yes	No
HEAD	Same as GET but no response body	No	Yes	Yes
OPTIONS	Describe communication options	No	Yes	Yes

Idempotent means making the same request multiple times produces the same result. *PATCH can be idempotent depending on implementation.

When to use PUT vs PATCH

PUT replaces the entire resource. Every field must be included. If a field is omitted, it is set to null or its default.

PATCH updates only the specified fields. Fields not included in the request body remain unchanged.

# PUT - replaces the entire user resource curl -X PUT https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"name":"Jane","email":"[email protected]","role":"admin"}' # PATCH - updates only the role field curl -X PATCH https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"role":"admin"}'

HTTP Status Codes (Most Common)

For a complete list of all codes, see our HTTP Status Codes Reference.

2xx Success

200OK. Request succeeded. Standard response for GET. 201Created. Resource was created. Return in response to POST. 204No Content. Success, but no body returned. Common for DELETE.

3xx Redirection

301Moved Permanently. Resource has a new permanent URL. 302Found. Temporary redirect. Method may change to GET. 304Not Modified. Cached version is still valid.

4xx Client Errors

400Bad Request. Malformed syntax or invalid parameters. 401Unauthorized. Authentication required or credentials invalid. 403Forbidden. Authenticated but not authorized for this resource. 404Not Found. Resource does not exist. 405Method Not Allowed. HTTP method not supported for this endpoint. 409Conflict. Request conflicts with current state (e.g., duplicate). 422Unprocessable Entity. Valid syntax but semantically incorrect. 429Too Many Requests. Rate limit exceeded. Check Retry-After header.

5xx Server Errors

500Internal Server Error. Generic server failure. 502Bad Gateway. Upstream server returned invalid response. 503Service Unavailable. Server is overloaded or under maintenance. 504Gateway Timeout. Upstream server did not respond in time.

Common HTTP Headers

Request Headers

Header	Purpose	Example
`Content-Type`	Format of the request body	`application/json`
`Accept`	Expected response format	`application/json`
`Authorization`	Authentication credentials	`Bearer eyJhbG...`
`User-Agent`	Client identifier	`MyApp/1.0`
`Cache-Control`	Caching directives	`no-cache`
`If-None-Match`	Conditional request (ETag)	`"abc123"`
`X-Request-ID`	Trace ID for debugging	`uuid-value`

Response Headers

Header	Purpose	Example
`Content-Type`	Format of response body	`application/json; charset=utf-8`
`Location`	URL of created resource	`/users/42`
`ETag`	Version identifier for caching	`"abc123"`
`Retry-After`	Seconds to wait after 429/503	`60`
`X-RateLimit-Limit`	Max requests per window	`1000`
`X-RateLimit-Remaining`	Requests left in window	`847`
`Link`	Pagination links	`</users?page=2>; rel="next"`

CORS Headers

Header	Purpose
`Access-Control-Allow-Origin`	Which origins can access the API
`Access-Control-Allow-Methods`	Allowed HTTP methods for CORS
`Access-Control-Allow-Headers`	Allowed request headers for CORS
`Access-Control-Max-Age`	How long preflight results can be cached (seconds)

Authentication Patterns

API Key (Header)

curl https://api.example.com/data \ -H "X-API-Key: your_api_key_here"

API Key (Query Parameter)

curl "https://api.example.com/data?api_key=your_api_key_here"

Security note: Query parameter API keys appear in server logs and browser history. Prefer header-based authentication when possible.

Bearer Token (JWT / OAuth2)

curl https://api.example.com/data \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Basic Auth

# Using -u flag (curl encodes to Base64 automatically) curl -u username:password https://api.example.com/data # Manual header (Base64 of "username:password") curl https://api.example.com/data \ -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

OAuth 2.0 Client Credentials Flow

# Step 1: Get access token curl -X POST https://auth.example.com/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET" # Step 2: Use the token curl https://api.example.com/data \ -H "Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1"

Curl Examples

GET request

curl https://api.example.com/users

GET with query parameters

curl "https://api.example.com/users?page=2&limit=25&sort=created_at"

GET with headers

curl https://api.example.com/users \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TOKEN"

POST with JSON body

curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -d '{"name":"Jane Doe","email":"[email protected]"}'

POST with form data

curl -X POST https://api.example.com/login \ -d "username=jane&password=secret123"

PUT (full update)

curl -X PUT https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"name":"Jane Doe","email":"[email protected]","role":"admin"}'

PATCH (partial update)

curl -X PATCH https://api.example.com/users/42 \ -H "Content-Type: application/json" \ -d '{"role":"admin"}'

DELETE

curl -X DELETE https://api.example.com/users/42 \ -H "Authorization: Bearer YOUR_TOKEN"

File upload

curl -X POST https://api.example.com/upload \ -F "file=@/path/to/document.pdf" \ -F "description=Quarterly report"

Verbose output (debugging)

# -v shows request/response headers curl -v https://api.example.com/users # -i includes response headers in output curl -i https://api.example.com/users # Save response to file curl -o response.json https://api.example.com/users # Follow redirects curl -L https://api.example.com/old-endpoint # Set timeout (seconds) curl --max-time 10 https://api.example.com/slow-endpoint

Useful curl flags

Flag	Purpose
`-X METHOD`	Set HTTP method
`-H "Header: Value"`	Add request header
`-d 'data'`	Send request body (sets POST by default)
`-F "field=value"`	Send multipart form data
`-u user:pass`	Basic authentication
`-v`	Verbose output (debug)
`-i`	Include response headers
`-o file`	Write output to file
`-L`	Follow redirects
`-s`	Silent mode (no progress bar)
`-k`	Skip SSL verification (dev only)
`--max-time N`	Timeout in seconds
`-w "%{http_code}"`	Print HTTP status code

Request Body Formats

JSON (most common)

Content-Type: application/json { "name": "Jane Doe", "email": "[email protected]", "tags": ["admin", "active"], "address": { "city": "Portland", "state": "OR" } }

Form URL-encoded

Content-Type: application/x-www-form-urlencoded name=Jane+Doe&email=jane%40example.com&role=admin

Multipart Form Data (file uploads)

Content-Type: multipart/form-data; boundary=----FormBoundary ------FormBoundary Content-Disposition: form-data; name="file"; filename="photo.jpg" Content-Type: image/jpeg (binary data) ------FormBoundary--

Pagination Patterns

Offset-based (most common)

GET /users?page=2&limit=25 GET /users?offset=25&limit=25

Cursor-based (better for large datasets)

GET /users?limit=25&after=eyJpZCI6NDJ9

Typical paginated response

{ "data": [...], "meta": { "total": 1042, "page": 2, "per_page": 25, "total_pages": 42 }, "links": { "first": "/users?page=1", "prev": "/users?page=1", "next": "/users?page=3", "last": "/users?page=42" } }

Error Response Patterns

Standard error format

{ "error": { "code": "validation_error", "message": "Invalid email format", "details": [ { "field": "email", "message": "Must be a valid email address", "value": "not-an-email" } ] } }

RFC 7807 Problem Details

{ "type": "https://api.example.com/errors/validation", "title": "Validation Error", "status": 422, "detail": "The 'email' field must be a valid email address", "instance": "/users/42" }

Best practice: Always return consistent error formats. Include a machine-readable error code, a human-readable message, and enough detail for the client to fix the problem.

API Versioning

URL path versioning (most common)

GET https://api.example.com/v1/users GET https://api.example.com/v2/users

Header versioning

curl https://api.example.com/users \ -H "Accept: application/vnd.example.v2+json"

Query parameter versioning

GET https://api.example.com/users?version=2

REST API Best Practices

Do	Don't
Use nouns for resources: `/users`	`/getUsers` or `/createUser`
Use plural nouns: `/users/42`	`/user/42`
Use HTTP methods for actions	Put verbs in URLs
Return 201 + Location header on create	Return 200 for everything
Use 204 for successful DELETE	Return the deleted resource
Nest sub-resources: `/users/42/posts`	Deeply nest beyond 2 levels
Use kebab-case in URLs: `/user-profiles`	camelCase or snake_case in URLs
Filter via query params: `?status=active`	Create separate endpoints per filter
Include rate limit headers	Rate limit without informing clients
Version your API from day one	Make breaking changes without versioning

URL structure examples

# Resource collections GET /users # List users POST /users # Create user GET /users/42 # Get user 42 PUT /users/42 # Replace user 42 PATCH /users/42 # Update user 42 DELETE /users/42 # Delete user 42 # Sub-resources GET /users/42/posts # List posts by user 42 POST /users/42/posts # Create post for user 42 # Filtering, sorting, pagination GET /users?role=admin&sort=-created_at&page=2&limit=25

Quick Navigation

HTTP Methods

When to use PUT vs PATCH

HTTP Status Codes (Most Common)

2xx Success

3xx Redirection

4xx Client Errors

5xx Server Errors

Common HTTP Headers

Request Headers

Response Headers

CORS Headers

Authentication Patterns

API Key (Header)

API Key (Query Parameter)

Bearer Token (JWT / OAuth2)

Basic Auth

OAuth 2.0 Client Credentials Flow

Curl Examples

GET request

GET with query parameters

GET with headers

POST with JSON body

POST with form data

PUT (full update)

PATCH (partial update)

DELETE

File upload

Verbose output (debugging)

Useful curl flags

Request Body Formats

JSON (most common)

Form URL-encoded

Multipart Form Data (file uploads)

Pagination Patterns

Offset-based (most common)

Cursor-based (better for large datasets)

Typical paginated response

Error Response Patterns

Standard error format

RFC 7807 Problem Details

API Versioning

URL path versioning (most common)

Header versioning

Query parameter versioning

REST API Best Practices

URL structure examples

Test Your APIs with ToolPipe

Related Tools