API

Good API design is crucial for system maintainability and developer experience.

API Design Principles

1. Consistency
   - Use consistent naming conventions
   - Follow similar patterns across endpoints

2. Simplicity
   - Easy to understand and use
   - Minimize required knowledge

3. Completeness
   - Cover all necessary operations
   - Handle edge cases

4. Evolution
   - Version your APIs
   - Backward compatibility

5. Documentation
   - Clear, comprehensive docs
   - Examples and tutorials

REST API Naming Conventions

Good:
GET    /users           (list users)
GET    /users/123       (get user 123)
POST   /users           (create user)
PUT    /users/123       (update user 123)
DELETE /users/123       (delete user 123)

Bad:
GET    /getUsers
POST   /createUser
GET    /user/delete/123

API Design Patterns

Pattern	Description	Example
Collection	List of resources	GET /users
Resource	Single resource	GET /users/123
Nested	Related resources	GET /users/123/orders
Action	Custom operations	POST /users/123/activate

API Versioning

Versioning Strategies:

1. URL Path
   /v1/users
   /v2/users

2. Header
   Accept: application/vnd.api.v2+json

3. Query Parameter
   /users?version=2

Recommended: URL path (visible, cacheable)

REST (Representational State Transfer) is the most common API architecture.

REST Constraints

1. Client-Server
   - Separation of concerns
   - Independent evolution

2. Stateless
   - No client context on server
   - Each request contains all info

3. Cacheable
   - Responses must indicate cacheability
   - Improves performance

4. Uniform Interface
   - Resource identification (URIs)
   - Resource manipulation through representations
   - Self-descriptive messages
   - HATEOAS (hypermedia)

5. Layered System
   - Client can't tell if connected to end server
   - Enables load balancing, caching

6. Code on Demand (optional)
   - Server can send executable code

HTTP Methods in REST

Method	Purpose	Idempotent	Safe
GET	Read resource	Yes	Yes
POST	Create resource	No	No
PUT	Replace resource	Yes	No
PATCH	Partial update	No	No
DELETE	Delete resource	Yes	No

REST Example

# Create user
POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

Response: 201 Created
{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2024-01-15T10:30:00Z"
}

# Get user
GET /api/v1/users/123

Response: 200 OK
{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}

REST Best Practices

1. Use nouns for resources, not verbs
2. Use HTTP methods for operations
3. Return appropriate status codes
4. Support pagination for lists
5. Use filtering and sorting
6. Implement rate limiting
7. Version your APIs

GraphQL is a query language for APIs that provides flexible data fetching.

GraphQL vs REST

REST: Multiple endpoints, fixed data structure
GET /users/123         → Full user object
GET /users/123/orders  → User's orders
GET /users/123/posts   → User's posts

GraphQL: Single endpoint, client specifies data
POST /graphql
{
  user(id: 123) {
    name
    email
    orders {
      id
      total
    }
  }
}
→ Only requested fields

GraphQL Schema

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]
  orders: [Order!]
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type Query {
  user(id: ID!): User
  users: [User!]
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String): User!
}

GraphQL Advantages

Advantage	Description
No over-fetching	Client requests only needed fields
No under-fetching	Single request for related data
Strong typing	Schema defines types
Introspection	Client can query schema
Versioning	Schema evolution, no versioning

GraphQL Challenges

1. Complexity
   - Learning curve
   - Schema design

2. Caching
   - HTTP caching doesn't work well
   - Need application-level caching

3. N+1 Problem
   - Query optimization required
   - DataLoader pattern

4. Security
   - Query complexity limits
   - Depth limiting