REST API

REST endpoints, request/response formats, error handling, pagination, filtering and sorting.

REST API

The REST API provides traditional RESTful endpoints for standard operations. Use REST when you prefer familiar HTTP methods and resource-based URLs.

REST Endpoints

Base URL:

https://api.example.com/api/v1

Common Endpoints:

Recordings: /api/v1/recordings
Meetings: /api/v1/meetings
Transcripts: /api/v1/recordings/{id}/transcript
Speakers: /api/v1/speakers
Folders: /api/v1/folders
Signals: /api/v1/signals
Users: /api/v1/users

Request/Response Formats

Request Format:

GET /api/v1/recordings HTTP/1.1
Host: api.example.com
Authorization: Bearer your_access_token
Content-Type: application/json
Accept: application/json

Response Format:

{
  "data": [
    {
      "id": 123,
      "title": "Team Meeting",
      "duration": 3600,
      "status": "completed",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 100
  },
  "links": {
    "first": "/api/v1/recordings?page=1",
    "last": "/api/v1/recordings?page=7",
    "next": "/api/v1/recordings?page=2"
  }
}

Create Request:

POST /api/v1/recordings HTTP/1.1
Content-Type: application/json
Authorization: Bearer your_access_token

{
  "title": "New Recording",
  "description": "Recording description",
  "folder_id": 456
}

Update Request:

PUT /api/v1/recordings/123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer your_access_token

{
  "title": "Updated Title"
}

Delete Request:

DELETE /api/v1/recordings/123 HTTP/1.1
Authorization: Bearer your_access_token

Error Handling

Handle API errors appropriately:

Error Response Format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "errors": {
      "title": ["The title field is required."],
      "folder_id": ["The selected folder id is invalid."]
    }
  }
}

HTTP Status Codes:

200 OK: Request successful
201 Created: Resource created successfully
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Error Handling Example:

try {
  const response = await fetch('/api/v1/recordings', {
    headers: {
      'Authorization': 'Bearer token',
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }
  
  const data = await response.json();
  return data;
} catch (error) {
  console.error('API Error:', error);
  // Handle error appropriately
}

Pagination

REST API responses are paginated:

Pagination Parameters:

page: Page number (default: 1)
per_page: Items per page (default: 15, max: 100)

Request:

GET /api/v1/recordings?page=2&per_page=20

Response:

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total": 150,
    "last_page": 8,
    "from": 21,
    "to": 40
  },
  "links": {
    "first": "/api/v1/recordings?page=1",
    "last": "/api/v1/recordings?page=8",
    "prev": "/api/v1/recordings?page=1",
    "next": "/api/v1/recordings?page=3"
  }
}

Use pagination links to navigate through results efficiently.

Filtering and Sorting

Filter and sort API responses:

Filtering:

GET /api/v1/recordings?filter[status]=completed&filter[folder_id]=123

Sorting:

GET /api/v1/recordings?sort=created_at&order=desc

Multiple Filters:

GET /api/v1/recordings?filter[status]=completed&filter[duration][min]=3600&sort=created_at&order=desc

Available Filters:

Status: filter[status]=completed|processing|failed
Folder: filter[folder_id]=123
Date Range: filter[created_at][from]=2024-01-01&filter[created_at][to]=2024-01-31
Duration: filter[duration][min]=3600&filter[duration][max]=7200
Tags: filter[tags][]=tag1&filter[tags][]=tag2

Sort Options:

sort=created_at (default)
sort=title
sort=duration
sort=updated_at
order=asc|desc (default: desc)

GraphQL API

GraphQL endpoint, GraphQL queries, GraphQL mutations, GraphQL schema, GraphQL examples.

Webhooks

Webhook setup, webhook events, webhook payloads, webhook security, webhook testing.