Api Design

API Design

The Squared API is designed to be RESTful, scalable, and easy to use. This document outlines the key principles and patterns used in our API design.

API Versioning

We use URL versioning for our API. All endpoints are prefixed with /api/v1/.

Example: https://api.squared.com/api/v1/tasks

Resource Naming

• Use plural nouns for resource names (e.g., /tasks, /users).
• Use kebab-case for multi-word resource names (e.g., /project-members).

HTTP Methods

• GET: Retrieve a resource
• POST: Create a new resource
• PUT: Update an entire resource
• PATCH: Partially update a resource
• DELETE: Remove a resource

Request/Response Format

• Use JSON for request and response bodies.
• Use camelCase for JSON property names.

Example response:

{
  "id": 1,
  "title": "Complete API documentation",
  "dueDate": "2023-06-30T00:00:00Z",
  "assignedTo": {
    "id": 101,
    "name": "John Doe"
  }
}

Error Handling

Use appropriate HTTP status codes and provide error messages in the response body.

Example error response:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The provided email is not valid."
  }
}

Authentication

We use JWT (JSON Web Tokens) for API authentication. Include the JWT in the Authorization header:

Authorization: Bearer <token>

Rate Limiting

API requests are rate-limited to prevent abuse. Limits are communicated via headers:

• X-RateLimit-Limit: Request limit per hour
• X-RateLimit-Remaining: Remaining requests in the current period
• X-RateLimit-Reset: Time when the limit resets (Unix timestamp)

Pagination

For endpoints returning multiple items, use cursor-based pagination:

• Include limit and cursor query parameters in the request.
• Return nextCursor in the response for fetching the next page.

Example: GET /api/v1/tasks?limit=20&cursor=<cursor>

Filtering and Sorting

• Use query parameters for filtering (e.g., ?status=active).
• Use the sort query parameter for sorting (e.g., ?sort=createdAt:desc).

For more detailed information about specific endpoints, refer to the API Reference documentation.