RESTful API Tasarımı: Prensipler ve En İyi Uygulamalar

RESTful API Design Principles

Designing a good API is crucial for the success of any application. This guide covers the fundamental principles and best practices for creating RESTful APIs that are intuitive, scalable, and maintainable.

1. REST Principles

REST (Representational State Transfer) is an architectural style for distributed systems:

Core Principles

• Stateless: Each request contains all information needed
• Client-Server: Separation of concerns
• Cacheable: Responses can be cached
• Uniform Interface: Consistent resource manipulation
• Layered System: Hierarchical architecture

2. Resource Design

Resources are the core of RESTful APIs:

Naming Conventions

# Good examples
GET /api/users
GET /api/users/123
POST /api/users
PUT /api/users/123
DELETE /api/users/123

# Nested resources
GET /api/users/123/posts
GET /api/users/123/posts/456

Resource Hierarchy

• Use nouns, not verbs
• Keep URLs short and meaningful
• Use plural nouns for collections
• Maintain consistency across endpoints

3. HTTP Methods

Use HTTP methods correctly for different operations:

CRUD Operations

# Create
POST /api/users
{
  "name": "John Doe",
  "email": "john@example.com"
}

# Read
GET /api/users
GET /api/users/123

# Update
PUT /api/users/123
PATCH /api/users/123

# Delete
DELETE /api/users/123

Method Semantics

• GET: Retrieve data (idempotent)
• POST: Create new resources
• PUT: Replace entire resource
• PATCH: Partial updates
• DELETE: Remove resources

4. Response Design

Well-designed responses improve API usability:

Standard Response Format

{
  "success": true,
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "message": "User created successfully"
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "field": "email",
      "value": null
    }
  }
}

5. Status Codes

Use appropriate HTTP status codes:

Common Status Codes

• 200 OK: Successful GET, PUT, PATCH
• 201 Created: Successful POST
• 204 No Content: Successful DELETE
• 400 Bad Request: Invalid request
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

6. Pagination

Implement pagination for large datasets:

Cursor-Based Pagination

GET /api/users?limit=20&cursor=eyJpZCI6MTIzfQ

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTQzfQ",
    "has_more": true,
    "total": 1000
  }
}

Offset-Based Pagination

GET /api/users?page=2&per_page=20

{
  "data": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 50,
    "total_count": 1000,
    "per_page": 20
  }
}

7. Filtering and Sorting

Provide flexible querying capabilities:

Filtering

# Filter by multiple criteria
GET /api/users?status=active&role=admin&created_after=2023-01-01

# Complex filtering
GET /api/users?filter[status]=active&filter[age][gte]=25&filter[age][lte]=35

Sorting

# Single field sorting
GET /api/users?sort=name

# Multiple field sorting
GET /api/users?sort=name,created_at

# Descending order
GET /api/users?sort=-created_at

8. Versioning

API versioning ensures backward compatibility:

URL Versioning

GET /api/v1/users
GET /api/v2/users

Header Versioning

GET /api/users
Accept: application/vnd.api+json;version=1

9. Security

Security is crucial for API design:

Authentication

• Use JWT tokens for stateless authentication
• Implement OAuth 2.0 for third-party access
• Use API keys for simple authentication
• Implement rate limiting

Authorization

• Implement role-based access control (RBAC)
• Use resource-level permissions
• Validate permissions on each request
• Log access attempts

10. Documentation

Good documentation is essential for API adoption:

OpenAPI/Swagger

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

Documentation Best Practices

• Provide interactive documentation
• Include code examples
• Document error responses
• Keep documentation updated

Conclusion

Designing a good RESTful API requires careful consideration of many factors. By following these principles and best practices, you can create APIs that are intuitive, scalable, and maintainable.

Remember that API design is an iterative process. Start with the basics, gather feedback from users, and continuously improve based on real-world usage.