API Reference

Overview of the RESTful API endpoints and how to use them

Available Endpoints

GET, POST, DELETEAPI Endpoint

/api/items

Manage items for workspaces

GET, PUT, DELETEAPI Endpoint

/api/items/:id

Manage individual items

POSTAPI Endpoint

/api/feedback

Submit user feedback

GETAPI Endpoint

/api/users

Retrieve user information

GET, PUT, DELETEAPI Endpoint

/api/users/:id

Manage individual users

GET, POSTAPI Endpoint

/api/workspaces

Manage workspaces

GET, PUT, DELETEAPI Endpoint

/api/workspaces/:id

Manage individual workspaces

Type-Safe API Client

The application provides a type-safe API client to simplify API requests and ensure type safety across the codebase. The client is implemented in lib/api-client.ts.

Type-Safe API Client

API Client Implementation

TYPESCRIPT

Type Definitions

API Client Type Definitions

TYPESCRIPT

Using the API Client

Example of using the API client to fetch items:

Using the API Client

TYPESCRIPT

React Query Integration

Example of using the API client with React Query:

React Query Integration

TYPESCRIPT

Authentication & Authorization

All API endpoints require authentication through Auth.js sessions. The server retrieves the current user using the getCurrentUser() function.

Authentication Flow

// 1. Retrieve the current user
const { user } = await getCurrentUser()

// 2. Check if the user exists
if (!user) {
  return NextResponse.json(
    { error: "Unauthorized" },
    { status: 401 }
  )
}

// 3. Proceed with authenticated operations
// ...

Rate Limiting

All API endpoints implement rate limiting using Upstash Ratelimit to prevent abuse. Rate limits are defined in the constants.ts file.

Rate limiting is essential to prevent abuse of your API. Make sure to implement it for all endpoints, especially those that perform write operations.

Rate Limit Implementation

TYPESCRIPT

Working with Items

Retrieving Items

Get all items or filter by workspace slug:

Retrieving Items

TYPESCRIPT

Creating Items

Create a new item in a workspace:

Creating Items

TYPESCRIPT

Deleting Items

Delete all items in a workspace (requires DELETE_WORKSPACE permission):

Deleting Items

TYPESCRIPT

Error Handling

The API consistently handles errors and returns appropriate status codes and error messages.

400

Validation Error

Input data failed validation

{
  error: "Validation Error",
  details: [
    {
      code: "invalid_type",
      path: ["values", "name"],
      message: "Required"
    }
  ]
}

401

Unauthorized

User is not authenticated or lacks permission

{
  error: "Unauthorized"
}

404

Not Found

Requested resource does not exist

{
  error: "Workspace not found"
}

429

Rate Limit Exceeded

Too many requests in a short period

{
  error: "Rate limit exceeded"
}

500

Internal Server Error

An unexpected error occurred on the server

{
  error: "Internal Server Error",
  details: "Error message"
}

Permissions System

API endpoints check permissions using the hasPermission utility function.

Permission Check Example

TYPESCRIPT

Best Practices

Request Handling

1
Always validate input data with Zod
2
Transform dates properly from strings
3
Log important events for debugging
4
Use rate limiting for all endpoints

Response Formatting

1
Return consistent JSON structures
2
Use appropriate HTTP status codes
3
Include detailed error messages
4
Use specific success messages

Security

1
Always check authentication for protected routes
2
Validate permissions for each operation
3
Sanitize user inputs and validate against schemas
4
Implement appropriate rate limiting

Data Access

1
Use parameterized queries to prevent SQL injection
2
Always check if resources exist before operations
3
Properly scope data access to authorized workspace
4
Use transactions for related operations

Client Integration

1
Use the ApiClient for type-safe requests
2
Handle errors consistently
3
Combine with React Query for data fetching
4
Provide proper loading and error states