API Basics: REST, HTTP, and Best Practices
An API (Application Programming Interface) allows different software applications to communicate with each other. REST (Representational State Transfer) is the most common architectural style for building web APIs, used by the majority of modern web services and mobile backends.
What is REST?
REST is an architectural style that uses standard HTTP methods to perform operations on resources. A RESTful API treats data as resources accessed via endpoints (URLs), and each endpoint represents a specific entity or collection. Resources are retrieved and manipulated using HTTP methods like GET, POST, PUT, PATCH, and DELETE. REST APIs are stateless — each request from a client contains all the information the server needs to fulfill it, which makes them highly scalable.
Anatomy of a REST Request
GET /api/users/123 HTTP/1.1 Host: api.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... Accept: application/json
HTTP Methods Overview
Each HTTP method maps to a specific CRUD operation. See our HTTP Methods Guide for a complete breakdown:
| Method | CRUD | Idempotent | Safe |
|---|---|---|---|
| GET | Read | Yes | Yes |
| POST | Create | No | No |
| PUT | Update (replace) | Yes | No |
| PATCH | Update (partial) | No | No |
| DELETE | Delete | Yes | No |
API Authentication with JWT
Most REST APIs require authentication to protect resources. JSON Web Tokens (JWTs) are the most common authentication mechanism for modern APIs. The client obtains a JWT from an authentication endpoint and includes it in the Authorization header of every subsequent request. This stateless approach means the server does not need to maintain session state, making it ideal for distributed systems and microservices.
Common HTTP Status Codes
| Code | Meaning | Use Case |
|---|---|---|
| 200 | OK | Successful GET or PUT request |
| 201 | Created | Resource successfully created via POST |
| 204 | No Content | Successful DELETE request |
| 301 | Moved Permanently | Resource has been moved to a new URL |
| 400 | Bad Request | Invalid client input or malformed syntax |
| 401 | Unauthorized | Missing or invalid authentication (send a valid JWT) |
| 403 | Forbidden | Authenticated but not authorized to access the resource |
| 404 | Not Found | Resource does not exist at this endpoint |
| 429 | Too Many Requests | Rate limit exceeded — slow down |
| 500 | Internal Server Error | Unexpected server failure |
Best Practices for API Design
• Use nouns for resource endpoints (e.g., /users, /orders), not verbs
• Leverage HTTP status codes consistently to communicate results
• Version your API (e.g., /v1/users) to maintain backward compatibility
• Use pagination, filtering, and sorting for list endpoints
• Always validate and sanitize input on the server side
• Implement rate limiting to protect your API from abuse
• Use HTTPS exclusively to encrypt data in transit
• Document your API with OpenAPI/Swagger for developer experience
• Return consistent error formats with meaningful messages