Open-source software for Joomla, Gitea, and web platforms. Home of MokoSuite, MokoGitea, and MokoCLI.

Tennessee

api/conventions

API Conventions

REST API design standards for all MokoConsulting services.

Endpoint Naming

Plural resource names: /backups, /profiles, /services
Lowercase with hyphens: /backup-profiles (not camelCase)
Nested resources for clear ownership: /profiles/{id}/backups
Version prefix: /api/v1/
Action endpoints use verbs only for non-CRUD operations: /backup/run

GET    /api/v1/{component}/{resources}           # List
GET    /api/v1/{component}/{resources}/{id}       # Get one
POST   /api/v1/{component}/{resources}            # Create
PATCH  /api/v1/{component}/{resources}/{id}        # Update
DELETE /api/v1/{component}/{resources}/{id}        # Delete

Response Format

Joomla APIs use JSON:API format:

{
  "links": {
    "self": "https://example.com/api/v1/mokosuitebackup/backups"
  },
  "data": [
    {
      "type": "backups",
      "id": "42",
      "attributes": {
        "status": "complete",
        "archive_size": 52428800,
        "created_at": "2026-06-01T12:00:00Z"
      }
    }
  ],
  "meta": {
    "total-pages": 3
  }
}

HTTP Status Codes

Code	Meaning	When to Use
200	OK	Successful GET, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but insufficient permissions
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Response Format

{
  "errors": [
    {
      "title": "Validation failed",
      "detail": "Field 'title' is required",
      "code": 422
    }
  ]
}

Pagination

Query parameters:

?page[offset]=0&page[limit]=20

Default limit: 20
Maximum limit: 50
Response includes meta.total-pages count

Filtering

Field-based filtering:

?filter[status]=complete&filter[profile_id]=1

Search:

?filter[search]=keyword

Sorting

?sort=created_at        # Ascending
?sort=-created_at       # Descending (prefix with -)

Date Format

All dates in ISO 8601 format with timezone: 2026-06-01T12:00:00Z

Pages