API Conventions

All smplkit APIs follow the JSON:API specification. Every request and response uses the JSON:API envelope format.

Request and Response Format

Creating a resource:

{
  "data": {
    "type": "resource-type",
    "attributes": {
      "name": "value"
    }
  }
}

Resource in a response:

{
  "data": {
    "id": "uuid",
    "type": "resource-type",
    "attributes": {
      "name": "value",
      "created_at": "2026-03-17T22:19:12Z",
      "updated_at": "2026-03-17T22:19:12Z"
    }
  }
}

List response:

{
  "data": [
    { "id": "uuid", "type": "resource-type", "attributes": { "..." : "..." } },
    { "id": "uuid", "type": "resource-type", "attributes": { "..." : "..." } }
  ]
}

HTTP Methods

Method	Usage
GET	Retrieve one or many resources
POST	Create a resource
PUT	Replace a resource entirely (full replacement, not partial update)
DELETE	Delete a resource

Status Codes

Code	Meaning
200	Success
201	Resource created
204	Resource deleted (no response body)
400	Validation error or malformed request
401	Missing or invalid authentication
403	Authenticated but not authorized
404	Resource not found
409	Conflict (e.g., duplicate key)

Error Responses

Errors follow JSON:API format and may include multiple errors:

{
  "errors": [
    {
      "status": "400",
      "title": "Validation Error",
      "detail": "Field required",
      "source": { "pointer": "/data/attributes/name" }
    }
  ]
}