Solidna integracja opiera się na stabilnych konwencjach dla statusów, opaque IDs, cursorów i metadanych, nie na przypadkowych szczegółach endpointu.
HTTP i status codes
Asynchroniczne create zwracają 202 Accepted, gdy praca trwa; udane odczyty 200. Błędy używają Problem Details i stabilnego code.
ID i czas
Traktuj file_..., job_..., task_... i project_id jako opaque strings. Timestampy są ISO 8601 UTC; nie wyciągaj znaczenia z kolejności ID.
Paginacja cursor
Listy używają opaque cursorów. Przekazuj next_cursor bez zmian, zachowuj filtry i nie twórz cursora po stronie klienta.
Nagłówki operacyjne
Wysyłaj Idempotency-Key przy powtarzalnych create i zapisuj X-Request-ID. Respektuj Retry-After i RateLimit-* przed retry.