Skip to main content

API Conventions

Standard patterns and conventions used throughout the PDaaS API.

Base URL​

https://api.console.solucao42.com.br

Request Format​

HTTP Methods​

  • GET - Retrieve resources
  • POST - Create resources
  • PUT - Full update (replace entire resource)
  • PATCH - Partial update (modify specific fields)
  • DELETE - Soft delete resource

Content Type​

All requests with a body must use:

Content-Type: application/json

Authentication​

All requests require HMAC authentication:

Authorization: HMAC {access_key}:{signature}
x-date: 2025-09-30T12:00:00Z
x-nonce: unique-identifier
x-content-sha256: body-hash

See Authentication for details.

Response Format​

JSON Structure​

All responses are JSON:

{
  "id": "res-123",
  "name": "Resource Name",
  "created_at": "2025-09-30T10:00:00Z"
}

Collection Responses​

List endpoints return paginated results:

{
  "total": 150,
  "page": 1,
  "results": [
    {"id": "1", "name": "Item 1"},
    {"id": "2", "name": "Item 2"}
  ]
}

Fields:

  • total - Total number of matching records
  • page - Current page number
  • results - Array of resources

Timestamps​

All timestamps use ISO 8601 format with UTC timezone:

{
  "created_at": "2025-09-30T10:00:00Z",
  "updated_at": "2025-09-30T12:30:00Z"
}

Pagination​

Query Parameters​

  • page - Page number (default: 1, min: 1)
  • quantity - Results per page (default: 20, min: 1, max: 100)
  • order_by - Sort field (prefix with - for descending)

Example​

GET /accounts?page=2&quantity=50&order_by=-created_at

Default Ordering​

When order_by is not specified, collections are ordered by created_at descending (newest first).

Filtering​

Include Deleted​

By default, soft-deleted resources are excluded. To include them:

GET /accounts?include_deleted=true

Note: Only administrators can view deleted resources.

Status Filtering​

Filter by resource status where applicable:

GET /service-accounts?include_inactive=true

Resource URLs​

URL Structure​

/{resource}              # List all
/{resource}/{id}         # Get specific
/{resource}/{id}/{sub}   # Nested resource

Examples​

GET    /accounts
POST   /accounts
GET    /accounts/acc-123
PATCH  /accounts/acc-123
DELETE /accounts/acc-123

GET    /service-accounts/sa-456/keys
POST   /service-accounts/sa-456/keys
DELETE /service-accounts/sa-456/keys/key-789

Organization Context​

Not in URL path. Organization and account context is inferred from:

  • JWT claims (for user authentication)
  • Service account access key (for HMAC authentication)
  • Subdomain (for public routes)
# ❌ WRONG
GET /organizations/org-123/accounts

# ✅ CORRECT
GET /accounts
Authorization: HMAC sa_mycomp_acc123_xyz:signature

HTTP Status Codes​

Success​

  • 200 OK - Successful GET, PUT, PATCH
  • 201 Created - Successful POST (resource created)
  • 204 No Content - Successful DELETE

Client Errors​

  • 400 Bad Request - Invalid request body, validation error
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn't exist
  • 409 Conflict - Resource already exists, state conflict
  • 422 Unprocessable Entity - Invalid input data
  • 429 Too Many Requests - Rate limit exceeded

Server Errors​

  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

Error Responses​

Standard Format​

{
  "error": "ErrorCode",
  "message": "Human-readable description",
  "details": {
    "field": "account_id",
    "reason": "Account not found"
  }
}

Validation Errors​

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Common Error Codes​

CodeStatusDescription
ValidationError422Request validation failed
Unauthorized401Authentication required
Forbidden403Insufficient permissions
NotFound404Resource not found
AlreadyExists409Resource already exists
RateLimitExceeded429Too many requests
InternalError500Server error

Rate Limiting​

Limits​

  • 1000 requests/minute per organization
  • 100 requests/minute per user/service account
  • 10 requests/second per IP address

Headers​

Response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1633024800

Rate Limit Exceeded​

429 Too Many Requests
Retry-After: 45
{
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 45 seconds"
}

Soft Delete​

Behavior​

All DELETE operations are soft deletes:

  1. Resource is marked with deleted_at timestamp
  2. Resource becomes invisible in list/get operations
  3. Data is preserved for audit and recovery
  4. Foreign key relations are maintained

Deleted Resource Fields​

{
  "id": "acc-123",
  "name": "Old Account",
  "deleted_at": "2025-09-30T12:00:00Z",
  "created_at": "2025-01-01T10:00:00Z"
}
  • deleted_at: null for active resources
  • deleted_at: ISO 8601 timestamp when deleted

Viewing Deleted Resources​

Only administrators can view deleted resources:

GET /admin/deleted/accounts

Restoring Resources​

Administrators can restore deleted resources:

POST /admin/restore/account/acc-123

Idempotency​

POST Idempotency​

POST requests for resource creation use unique constraints to prevent duplicates:

  • Organization slug (unique globally)
  • Account name (unique per organization)
  • Group name (unique per organization)
  • Policy name (unique per organization)

PUT/PATCH Idempotency​

PUT and PATCH requests are naturally idempotent:

PATCH /accounts/acc-123
{
  "name": "Updated Name"
}

Multiple identical requests produce the same result.

DELETE Idempotency​

DELETE requests are idempotent. Deleting an already-deleted resource returns:

400 Bad Request
{
  "error": "AlreadyDeleted",
  "message": "Resource is already deleted"
}

Versioning​

Current Version​

API version: v1 (implied, not in URL)

Future Versions​

When breaking changes are introduced, a new version will be released:

https://api.console.solucao42.com.br/v2/...

Version 1 will remain available with a deprecation timeline.

CORS​

Allowed Origins​

  • * (development only)
  • Configured origins (production)

Preflight Requests​

OPTIONS requests are supported for CORS preflight:

OPTIONS /accounts
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, x-date, x-nonce, x-content-sha256

Request ID​

Correlation ID​

Every request is assigned a unique correlation ID:

x-correlation-id: 550e8400-e29b-41d4-a716-446655440000

This ID is:

  • Returned in response headers
  • Logged in audit trail
  • Used for debugging and support

Next Steps​