Конвенции
Pagination, filtering, ETag, idempotency, long-running ops.
Pagination
Cursor-based, без offset:
GET /v1/instances?limit=50&cursor=eyJpZCI6Imkt...Ответ:
{
"items": [...],
"next_cursor": "eyJpZCI6Imkt...",
"has_more": true
}Filtering
GET /v1/instances?project=prod&status=running&label.env=prodETag и optimistic locking
PUT /v1/instances/i-7f9a2c01 HTTP/1.1
If-Match: "rev-42"При расхождении — 412 Precondition Failed.
Идемпотентность
POST'ы принимают Idempotency-Key (UUID v4). Повторный вызов в течение 24h
с тем же ключом возвращает кэшированный ответ.
Long-running operations
Создание ресурса возвращает 202 Accepted + Location: /v1/operations/op-...:
GET /v1/operations/op-91283 HTTP/1.1{ "id": "op-91283", "status": "running", "progress": 0.7 }После done — 200 OK + ссылка на ресурс.