REST (Representational State Transfer) is an architectural style for designing networked applications. The core principles are:

• Stateless: Each request contains all information needed to process it
• Client-Server: Separation of concerns between client and server
• Cacheable: Responses should be cacheable when appropriate
• Uniform Interface: Consistent way to interact with resources
• Layered System: Architecture can be composed of hierarchical layers
• Code on Demand (optional): Server can send executable code to client

REST uses resources identified by URIs and standard HTTP methods to perform operations.

A RESTful API follows these characteristics:

• Uses HTTP methods appropriately (GET, POST, PUT, DELETE)
• Resources are identified by URIs (e.g., /users/123)
• Stateless communication
• Returns appropriate HTTP status codes
• Uses standard media types (JSON, XML)
• Implements HATEOAS (Hypermedia as the Engine of Application State)

Example of RESTful endpoints:

GET /users          # Get all users
GET /users/123      # Get specific user
POST /users         # Create new user
PUT /users/123      # Update user
DELETE /users/123   # Delete user

Resources are the key abstraction in REST. A resource is any information that can be named and addressed. Resources should be:

• Nouns, not verbs: Use /users not /getUsers
• Hierarchical: /users/123/orders/456
• Consistent: Use plural nouns (/users, not /user)
• Meaningful: Clear and descriptive names

Resources represent entities in your domain model and should map to business objects or data entities.

POST:

• Creates new resources
• Not idempotent (multiple calls create multiple resources)
• Server determines resource identifier
• Example: POST /users creates a new user

PUT:

• Creates or updates resources
• Idempotent (multiple identical calls have same effect)
• Client provides resource identifier
• Example: PUT /users/123 creates or updates user with ID 123

2xx Success:

• 200 OK: Successful GET, PUT, PATCH
• 201 Created: Successful POST
• 204 No Content: Successful DELETE or PUT with no response body

4xx Client Error:

• 400 Bad Request: Invalid request syntax
• 401 Unauthorized: Authentication required
• 403 Forbidden: Access denied
• 404 Not Found: Resource doesn't exist
• 409 Conflict: Resource conflict
• 422 Unprocessable Entity: Validation errors

5xx Server Error:

• 500 Internal Server Error: Generic server error
• 503 Service Unavailable: Server temporarily unavailable

Authentication: Verifies who the user is (identity verification)

• "Are you really John Doe?"
• Methods: passwords, biometrics, certificates

Authorization: Determines what the authenticated user can do (permission checking)

• "Can John Doe access this resource?"
• Methods: roles, permissions, ACLs

Both are typically required for secure APIs. Authentication happens first, then authorization checks permissions.

Return 422 Unprocessable Entity with detailed field-level errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be valid format"
      },
      {
        "field": "password",
        "code": "TOO_SHORT",
        "message": "Password must be at least 8 characters"
      }
    ]
  }
}

This helps clients understand exactly what needs to be fixed.

CORS (Cross-Origin Resource Sharing) allows controlled access to resources from different domains.

CORS Headers:

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 3600

Preflight Requests: Browser sends OPTIONS request for complex requests.

Security Considerations:

• Don't use * for credentials-enabled requests
• Be specific with allowed origins
• Validate origins server-side
• Consider using CORS libraries

HATEOAS (Hypermedia as the Engine of Application State) means that API responses should include links to related actions or resources. This makes APIs self-discoverable and reduces client-server coupling.

Example response with HATEOAS:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "edit": "/users/123",
    "delete": "/users/123"
  }
}

Benefits include improved API discoverability, reduced documentation needs, and easier API evolution.

PUT: Replaces the entire resource with the provided data. If you omit fields, they should be set to default/null values.

PATCH: Partial update of a resource. Only updates the fields provided in the request body.

Example:

PUT /users/123
{
  "name": "John Doe",
  "email": "john@example.com"
}
# Replaces entire user object

PATCH /users/123
{
  "email": "newemail@example.com"
}
# Only updates email field