API Standards

This document defines the API conventions used across the autom8y platform. Following these standards ensures consistency and interoperability between services.

General Principles

1. RESTful Design

APIs follow REST principles where applicable:

Use HTTP methods semantically (GET, POST, PUT, DELETE)
Resources are nouns, not verbs
Use plural resource names (/workflows, not /workflow)

2. Versioning

All APIs are versioned in the URL path:

https://api.autom8y.io/v1/workflows
https://api.autom8y.io/v2/workflows

Request Format

Headers

Required headers for all requests:

Header	Description	Example
`Content-Type`	Request body format	`application/json`
`Accept`	Response format	`application/json`
`Authorization`	Authentication	`Bearer <token>`
`X-Request-ID`	Tracing identifier	`uuid-v4`

Body Structure

Request bodies use JSON with snake_case keys:

{
  "workflow_name": "data-sync",
  "trigger_type": "schedule",
  "schedule_config": {
    "cron_expression": "0 */6 * * *",
    "timezone": "UTC"
  }
}

Response Format

Success Responses

Successful responses wrap data in a consistent envelope:

{
  "data": {
    "id": "wf_abc123",
    "name": "data-sync",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

List Responses

Collections include pagination metadata:

{
  "data": [
    { "id": "wf_abc123", "name": "workflow-1" },
    { "id": "wf_def456", "name": "workflow-2" }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Error Responses

Errors follow RFC 7807 Problem Details format:

{
  "type": "https://api.autom8y.io/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "The 'workflow_name' field is required",
  "instance": "/v1/workflows",
  "errors": [
    {
      "field": "workflow_name",
      "code": "required",
      "message": "This field is required"
    }
  ]
}

Status Codes

Success Codes

Code	Meaning	When to Use
`200`	OK	Successful GET, PUT
`201`	Created	Successful POST creating resource
`204`	No Content	Successful DELETE

Client Error Codes

Code	Meaning	When to Use
`400`	Bad Request	Invalid request format
`401`	Unauthorized	Missing/invalid authentication
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource doesn’t exist
`409`	Conflict	Resource state conflict
`422`	Unprocessable	Semantic validation failure
`429`	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Meaning	When to Use
`500`	Internal Error	Unexpected server failure
`502`	Bad Gateway	Upstream service failure
`503`	Service Unavailable	Temporary unavailability
`504`	Gateway Timeout	Upstream timeout

Authentication

Bearer Tokens

API authentication uses Bearer tokens:

curl -H "Authorization: Bearer <token>" \
  https://api.autom8y.io/v1/workflows

Token Scopes

Tokens are scoped to specific permissions:

Scope	Access
`workflows:read`	Read workflow definitions
`workflows:write`	Create/modify workflows
`workflows:execute`	Trigger workflow runs
`analytics:read`	Query analytics data

Rate Limiting

Limits

Default rate limits per authentication level:

Level	Requests/Minute
Unauthenticated	60
Authenticated	1000
Service Account	5000

Headers

Rate limit status is returned in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705312800

Pagination

Request Parameters

Parameter	Description	Default
`page`	Page number (1-indexed)	1
`per_page`	Items per page	20
`sort`	Sort field	`created_at`
`order`	Sort direction	`desc`

Example

GET /v1/workflows?page=2&per_page=50&sort=name&order=asc

Filtering

Use query parameters for filtering:

GET /v1/workflows?status=active&trigger_type=schedule

Complex filters use bracket notation:

GET /v1/workflows?created_at[gte]=2024-01-01&created_at[lt]=2024-02-01

Idempotency

For POST/PUT requests, include an idempotency key:

curl -X POST \
  -H "Idempotency-Key: unique-request-id" \
  https://api.autom8y.io/v1/workflows

The same key within 24 hours returns the cached response.

Next Steps

Review Domain Routing for URL structure
Explore the Architecture for service details