API Design Guide

Version 1.0.0 · Published 2026 Feb 19

Purpose

Standards and best practices for REST API components within this project.

Guiding Principles

• Use commonly accepted web standards (HTTP, JSON)
• Be consistent with accepted practices
• Simple to consume and test
• Pragmatic and performant

Requests

URIs/Paths

• URIs should be intuitive (affordance)
• Keep URIs simple and short
• Use plural resource names: /images
• Use nouns, not verbs: /images/4 not /get_images_by_id

HTTP Verbs

Method	Action
GET	Read
POST	Create
PUT	Update (full)
PATCH	Update (partial)
DELETE	Delete

Resource Identifiers

Use Sequential UUIDs (SQUUIDs). Never expose database row IDs.

Versioning

Two methods supported:

GET /images/4
Accept: application/vnd.hybrid-compute.v1+json

Or in URI:

GET /v1/images/4

Format: Major.Minor (x.y). Change Major for multiple breaking changes, Minor for 1+ breaking changes.

Pagination

Use offset and limit with HAL links:

{
  "_links": {
    "self": { "href": "/images?offset=543&limit=25" },
    "next": { "href": "/images?offset=768&limit=25" },
    "prev": { "href": "/images?offset=123&limit=25" }
  },
  "items": []
}

Security

• Always use HTTPS
• Authentication validates consumer
• Authorization ensures permission

Responses

HTTP Status Codes

Code	Meaning
200	OK
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Error Format

{
  "errors": [
    {
      "code": "not_found",
      "title": "Image not found",
      "details": "No image found with ID: abc123"
    }
  ]
}

JSON Formatting

• Dates: RFC 3339 UTC format (2008-09-08T22:47:31Z)
• UTF-8 encoding
• Currency with code, value, exponent

Performance

• Use pagination for large result sets
• Enable HTTP compression (60-80% reduction)
• Use ETag for caching

REST API Reference

Images

Method	Endpoint	Description
POST	/v1/images	Upload image
GET	/v1/images	List images
GET	/v1/images/:id	Get image
POST	/v1/images/:id/tiles	Split into tiles

Tiles

Method	Endpoint	Description
GET	/v1/tiles	List tiles
POST	/v1/tiles/:id/upscale	Upscale tile

Jobs

Method	Endpoint	Description
POST	/v1/stitch	Stitch tiles
GET	/v1/jobs/:id	Job status

Commit Standards

type(scope): short description (≤60 chars)
- optional bullet point

Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert