Backend Api Standards

Backend API Standards Skill

This skill establishes mandatory standards for REST API contracts and data format. It defines what the API must return and how data must be shaped — it does not prescribe backend structure, folders, or implementation details.

When to Use This Skill

• When designing or documenting a new API endpoint
• When the user mentions "API", "endpoint", "REST", "response format"
• When defining request/response schemas or data models
• To ensure all APIs follow the same contract conventions

Core Standards

1. Unified Response Format

Every single API response MUST follow this exact structure:

{
  "status": "success",
  "message": "Human-readable description of the result",
  "data": {},
  "meta": null
}

Response Fields Specification

| Field | Type | Required | Description | | --------- | ------------------------- | -------- | ----------------------------------------------------------------------- | | status | "success" \| "error" | Always | Indicates if the request succeeded | | message | string | Always | Human-readable description | | data | object \| array \| null | Always | Response payload. Use null when there's no data to return | | meta | object \| null | Always | Pagination, filters, or additional metadata. Use null when not needed |

Success Response Examples

Resource retrieved:

{
  "status": "success",
  "message": "Credit cards retrieved successfully.",
  "data": [
    {
      "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
      "alias": "Mercado Pago",
      "color": "#007bff",
      "total_debt": "837.83",
      "payment_due_day": 18,
      "statement_close_day": 7,
      "credit_limit": "2900.00",
      "metadata": {},
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": null
}

Resource created:

{
  "status": "success",
  "message": "Credit card created successfully.",
  "data": {
    "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
    "alias": "New Card",
    "credit_limit": "5000.00",
    "metadata": {},
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "meta": null
}

Resource deleted (no content to return):

{
  "status": "success",
  "message": "Transaction deleted successfully.",
  "data": null,
  "meta": null
}

Paginated list:

{
  "status": "success",
  "message": "Products retrieved successfully.",
  "data": [{ "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A2", "name": "Product 1" }],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_items": 150,
    "total_pages": 8
  }
}

Error Response Examples

Validation error:

{
  "status": "error",
  "message": "Validation failed.",
  "data": {
    "errors": {
      "email": ["The email field is required."],
      "password": ["Password must be at least 8 characters."]
    }
  },
  "meta": null
}

Authentication error:

{
  "status": "error",
  "message": "Unauthenticated.",
  "data": null,
  "meta": null
}

Authorization error:

{
  "status": "error",
  "message": "You do not have permission to perform this action.",
  "data": null,
  "meta": null
}

Resource not found:

{
  "status": "error",
  "message": "Credit card not found.",
  "data": null,
  "meta": null
}

Server error (no details exposed):

{
  "status": "error",
  "message": "Internal server error.",
  "data": null,
  "meta": null
}

2. Mandatory OpenAPI Documentation

Every API endpoint MUST be documented using OpenAPI 3.0+ specification.

Delivery Requirements

• Each project must expose an OpenAPI specification endpoint (e.g., /api/docs/openapi.json)
• Swagger UI or Scalar must be available at /api/docs
• Every endpoint must be fully documented with:
• Summary and description
• All path, query, and header parameters
• Request body schema (when applicable)
• All possible response schemas (including errors)
• Security requirements

OpenAPI Example

openapi: 3.0.3
info:
  title: Credit Cards API
  version: 1.0.0
  description: API for managing credit cards and transactions
servers:
  - url: /api
    description: Base API path

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ApiResponse:
      type: object
      required: [status, message, data, meta]
      properties:
        status:
          type: string
          enum: [success, error]
        message:
          type: string
        data:
          nullable: true
        meta:
          nullable: true
          type: object
          properties:
            current_page: { type: integer }
            per_page: { type: integer }
            total_items: { type: integer }
            total_pages: { type: integer }

    CreditCard:
      type: object
      properties:
        id:
          type: string
          format: ulid
          example: "01JQ5B3K7MNP9R8V2WX4Y6Z0A1"
        alias:
          type: string
          example: "Mercado Pago"
        color:
          type: string
          pattern: "^#[0-9a-fA-F]{6}$"
          example: "#007bff"
        total_debt:
          type: string
          format: decimal
          example: "837.83"
        payment_due_day:
          type: integer
          minimum: 1
          maximum: 31
        statement_close_day:
          type: integer
          minimum: 1
          maximum: 31
        credit_limit:
          type: string
          format: decimal
          example: "2900.00"
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

paths:
  /credit-cards:
    get:
      tags: [Credit Cards]
      summary: List user's credit cards
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: per_page
          in: query
          schema: { type: integer, default: 20 }
      responses:
        "200":
          description: Credit cards retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/CreditCard"
        "401":
          $ref: "#/components/responses/Unauthenticated"

3. ULID for Resource Identifiers

All resource IDs exposed by the API MUST use ULID format instead of auto-increment integers or UUIDs.

ULID Format

• 26 characters, Crockford's Base32 encoded
• Example: 01JQ5B3K7MNP9R8V2WX4Y6Z0A1
• Sortable by generation time
• URL-safe (no special characters)

Use in API

{
  "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
  "user_id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A2"
}

All references between resources (foreign keys exposed in the API) must also use ULID strings.

4. JWT Authentication

All protected endpoints MUST authenticate via JWT sent in the Authorization header.

Request Header

Authorization: Bearer 

Token Lifetime

• Access token: 15–60 minutes
• Refresh token: 7–30 days
• Algorithm: HS256 (single service) or RS256 (microservices)

Token Payload Structure

{
  "sub": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
  "email": "user@example.com",
  "iat": 1687700000,
  "exp": 1687703600,
  "type": "access"
}

Login Response Format

{
  "status": "success",
  "message": "Authenticated successfully.",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900
  },
  "meta": null
}

5. Mandatory Entity Fields

Every resource exposed by the API MUST include these three fields in its representation:

| Field | Type | Description | | ------------ | ---------------------------- | ---------------------------------------------------------- | | created_at | string (ISO 8601 UTC) | Timestamp when the resource was created. Never changes. | | updated_at | string (ISO 8601 UTC) | Timestamp of the last modification. | | metadata | object (free-form key/val) | Optional extra information not covered by the main schema. |

Format

• Timestamps: ISO 8601 in UTC with Z suffix (e.g., 2025-01-15T10:30:00Z).
• metadata: always an object. Defaults to {} when empty, never null.

Example

{
  "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
  "alias": "Mercado Pago",
  "credit_limit": "2900.00",
  "metadata": {
    "source": "mobile_app",
    "imported_from": "legacy_system",
    "custom_color": "#ff5733"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T14:20:15Z"
}

Purpose of metadata

The metadata field allows sending additional context without altering the resource schema or introducing new fields for every small variation. Clients should never rely on a specific metadata key being present unless explicitly documented for that endpoint.

6. Data Format Conventions

Consistent data shapes across every resource in the API:

| Data Type | Format | Example | | ------------- | ----------------------------------------------------- | ------------------------------ | | Identifiers | ULID string | "01JQ5B3K7MNP9R8V2WX4Y6Z0A1" | | Timestamps | ISO 8601 UTC string | "2025-01-15T10:30:00Z" | | Dates (only) | YYYY-MM-DD | "2025-01-15" | | Decimals | String (to preserve precision) | "2900.00" | | Integers | Number | 18 | | Booleans | true / false | true | | Enums | lowercase snake_case string | "pending_review" | | Colors (hex) | #rrggbb | "#007bff" | | Field naming | snake_case | payment_due_day | | Currency | Amount as string + separate ISO 4217 currency field | "100.00", "USD" | | Empty lists | [] (never null) | [] | | Empty objects | {} (never null, e.g., for metadata) | {} | | Unknown value | null (used only when the value is genuinely absent) | null |

7. HTTP Status Codes

| Code | When to Use | | ---- | ---------------------------------------------------- | | 200 | Successful GET, PUT, PATCH | | 201 | Successful POST (resource created) | | 204 | Successful DELETE (no content to return, data: null) | | 400 | Malformed request | | 401 | Missing or invalid authentication | | 403 | Authenticated but insufficient permissions | | 404 | Requested resource not found | | 422 | Validation errors | | 429 | Rate limit exceeded | | 500 | Unexpected server error |

8. Sensitive Data

The API MUST NEVER return:

• Password hashes or raw passwords
• Internal tokens, secret keys, or private credentials
• Stack traces, raw exceptions, or internal error details
• Internal database IDs (use ULIDs instead)

Error responses in production must use the generic error format defined in Section 1 — never leak internal information.

9. Logging System (Mandatory)

Every API MUST implement a structured logging system. Logs are essential for observability, debugging, auditing, and incident response in production.

Requirements

• Use structured logging (JSON) rather than plain text, so logs are machine-parseable.
• Assign a correlation/request ID (e.g., request_id, ideally a ULID) to every

incoming request and include it in all log entries for that request. Return it in a response header (e.g., X-Request-Id) so clients and servers can be cross-referenced.

• Log at minimum, for every request: HTTP method, path, status code, latency (ms),

authenticated user id (when present), and the request_id.

• Log the complete request (method, path, query params, headers, and body) and the

complete response (status code, headers, and body) for each request — with sensitive fields masked/redacted (see security note below).

• Log all errors and unhandled exceptions with full stack traces server-side only

— never expose them in the API response (see Section 8). When something crashes, the log MUST indicate the exact code location (file, line, function/method, and the full stack trace) so the failure can be traced back to its source.

• Use appropriate log levels: debug, info, warning, error, critical.

Standard Log Levels

| Level | When to Use | | ---------- | ----------------------------------------------------------------- | | debug | Detailed diagnostic info, disabled in production by default | | info | Normal events: request received, resource created, job completed | | warning | Unexpected but recoverable situations (deprecated usage, retries) | | error | A request failed or an operation could not be completed | | critical | System-level failures requiring immediate attention |

Structured Log Entry Example

{
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "info",
  "request_id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
  "method": "POST",
  "path": "/api/credit-cards",
  "status_code": 201,
  "latency_ms": 42,
  "user_id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A2",
  "message": "Credit card created successfully."
}

Full Request/Response Log Example

{
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "info",
  "request_id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A1",
  "request": {
    "method": "POST",
    "path": "/api/credit-cards",
    "query": {},
    "headers": { "content-type": "application/json", "authorization": "Bearer ***" },
    "body": { "alias": "New Card", "credit_limit": "5000.00" }
  },
  "response": {
    "status_code": 201,
    "headers": { "content-type": "application/json" },
    "body": { "status": "success", "message": "Credit card created successfully.", "data": { "id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A3" }, "meta": null }
  },
  "latency_ms": 42
}

Crash / Exception Log Example

When an unhandled error occurs, log where it crashed (file, line, function) plus the full stack trace — server-side only:

{
  "timestamp": "2025-01-15T10:31:12.880Z",
  "level": "error",
  "request_id": "01JQ5B3K7MNP9R8V2WX4Y6Z0A4",
  "method": "POST",
  "path": "/api/credit-cards",
  "status_code": 500,
  "error": {
    "type": "NullPointerException",
    "message": "credit_limit is null",

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ErikaAX08](https://github.com/ErikaAX08)
- **Source:** [ErikaAX08/erikas-skills](https://github.com/ErikaAX08/erikas-skills)
- **License:** MIT
- **Homepage:** https://github.com/ErikaAX08/erikas-skills#readme

Install and usage instructions live in the source repository linked above.