API ката коддору жана best practices

1) Эмне үчүн каталарды стандартташтыруу

кардарлар үчүн алдын ала: бирдиктүү формат жана retrains жүрүм-туруму.
Дебагды тездетүү: 'trace _ id '/' request _ id', туруктуу 'error _ code'.
Коопсуздук: SQL/stack traces/конфиги агып жок.
Байкоо: каталардын таксономиясы боюнча отчеттуулук (валидация, квота, таймауттар ж.б.).

2) Негизги принциптер

1. Бардык 4xx/5xx үчүн бирдиктүү жооп форматы (жана 2xx үчүн жарым-жартылай каталар өзүнчө схема).
2. Так семантика HTTP: туура статусу маанилүү болуп саналат.
3. Эки деңгээл коду: транспорт ('status') жана туруктуу домен 'error _ code'.
4. Retriable vs Non-retriable: ачык-айкын көрсөтүп, бэк-оффко бир эскертүү бериңиз.
5. демейки коопсуздук: маалымат - укуктар менен кардар гана; ички жолдору жок.
6. Локализация: машина коду туруктуу бойдон калууда, текст - которуу.

3) Бирдиктүү ката формат (RFC 7807 негизинде)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

Милдеттүү: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Кошумча: 'errors []' (талаалар боюнча), 'retriable', 'hint', 'meta'.

• `Content-Type: application/problem+json`
• `X-Request-ID`/`Traceparent` (W3C)
• (429/503 үчүн) 'Retry-After' (секунд же датасы)

4) HTTP статустарынын семантикасы ("классика" жана практиканы бириктирүү)

2xx (нюанстар менен ийгилик)

200 OK - кадимки ийгилик.
201 Created - түзүлгөн ресурс (Location).
202 Кабыл алынган - асинхрондук кезек (бер 'status _ url').
207 Multi-Status - жарым-жартылай ийгилик (мүмкүн болсо, алыс).

4xx (кардар ката)

400 Bad Request - синтаксис/формат, бирок талааларды валидациялоо эмес (жакшыраак 422).
401 Unauthorized - жок/туура эмес токен. Келгиле, 'WWW-Authenticate'.
403 Forbidden - токен validen, бирок укуктары жетишсиз (RBAC/ABAC/лимиттер).
404 Not Found - ресурс/пункту жок.
409 Conflict - версиялардын/абалдын карама-каршылыгы (optimistic locking, idempotency).
410 Gone - EndPoint түбөлүккө алынып салынат.
412 Precondition Failed - ETag/If-Match өткөн жок.
415 Unsupported Media Type - туура эмес 'Content-Type'.
422 Unprocessable Entity - бизнес эрежелеринин валидациясы.
429 Too Many Requests - ашпаган квота/ылдамдык (караңыз § 7).

5xx (сервер катасы)

500 Internal Server Error - күтүлбөгөн ката; майда-чүйдөсүнө чейин ачыкка чыгарбоо керек.
502 Bad Gateway - апстрим ката.
503 Service Unavailable - деградация/ашыкча жүктөө, бериңиз 'Retry-After'.
504 Gateway Timeout - арткы таймаут.

5) Домендик таксономия 'error _ code'

• 'AUTH _' - аутентификация/авторизация.
• 'VAL _' - кириш маалыматтарды валидациялоо.
• 'RATELIMIT _' - квота жана ылдамдык.
• 'IDEMP _' - демпотенттүүлүк/дубликаттар.
• 'CONFLICT _' - версиялары/абалы.
• 'DEP _' - көз карандылык (PSP/DNS/SMTP).
• 'PAY _' - төлөм доменинин бизнес каталары.
• 'SEC _' - коопсуздук (кол тамгалар, HMAC, mTLS).
• 'INT _' - ички капыстан.

• Убакыттын туруктуулугу (back-compat).
• Каталар каталогундагы сүрөттөмөлөр жана мисалдар (docs + machine-readable JSON).

6) Retriable vs Non-retriable

• `retriable: true|false`
• Эгерде 'true' - сөзсүз 'Retry-After' (секунд менен) же келишим "экспоненциалдык бэк-офф (1-2 с баштап, макс 30-60 с)".

Retriable адатта: '502/503/504', кээ бир '500', '429' (терезеден кийин).
Non-retriable: `400/401/403/404/409/410/415/422`.

7) Rate Limit & Quota ката (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• `Retry-After: 12`
• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
• Для квот: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`

8) Идемпотенттик жана чыр-чатактар

жазуу үчүн суроо-жылы - "Idempotency-Key" (24-72 саат ичинде уникалдуу).
Кайра иштетүү чыр-чатак → 409 Conflict менен 'error _ code: "IDEMP_REPLAY"'.
ETag → 412 Precondition Failed боюнча ресурстун версияларынын чыр-чатагы.
Жооп катары коопсуз кайталап суроо үчүн 'resource _ id '/' status _ url' тиркеңиз.

9) Валидация жана 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• Ошол эле 400 кайталанбайт - 422 бизнес-валидация үчүн артыкчылык.
• Билдирүүлөр - адам окулуучу; 'code' - машина.

10) ката коопсуздук

Эч качан: stack жолдору, SQL, файлдардын жолдору, жеке менчик хост аттары.
PII түзөтүү; GDPR/DSAR мониторинг жүргүзүү.
Кол коюу үчүн/НМАС: "SEC _ SIGNATURE _ MISMATCH" (403) жана "SEC _ TIMESTAMP _ SKEW" (401/403) "текшерүү убактысы ± 5 мин".

11) Корреляция жана байкоо

Ар дайым 'trace _ id '/' X-Request-ID' кошуп, логинге/жолдорго ыргытыңыз.
Каталар 'error _ code' жана 'status' → dashboard 'top-каталар', 'new vs known'.
Alerty: 5xx/422/429, жашыруун p95, share of errors.

12) gRPC/GraphQL/Webhooks - Mappings

gRPC ↔ HTTP

GraphQL

Транспорт 200, бирок 'errors []' ичинде - 'extensions кошуу. code` и `trace_id`.
"Фатал" үчүн (аутентификация/квота) - жакшы чыныгы HTTP 401/403/429.

Webhooks

2xx алуучуну гана ийгиликтүү деп эсептеңиз.
Экспоненциалдык бэк-офф менен ретрайлер, 'X-Webhook-ID', 'X-Signature'.
410 алуучудан - ретрацияны токтотуу (endpoint алынып салынган).

13) Каталарды чыгаруу

'type '/' error _ code' - туруктуу; жаңы - гана кошуу.
дене схемасы өзгөргөндө - API же 'problem + json чакан нускасын жогорулатуу; v=2`.
Документация: коддор таблицасы + мисалдар; changelog каталар.

14) Документтер (OpenAPI үзүндүлөр)

Глобалдык жооптор

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

Эндпоинттин мисалы

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) тестирлөө жана сапаты

Келишим-тесттер: шайкештик 'application/problem + json', милдеттүү талаалар.
Терс тесттер: бардык бутактары 401/403/404/ 409/422/429/500.
Chaos/latency: 5xx/ 503/504/429 ('Retry-After') боюнча retrains текшерүү.
Коопсуздук тесттер: ички билдирүүлөр жок, туура PII маска.
Backward-compat: эски кардарлар жаңы талааларды түшүнүшөт (кошуу, сындырбоо).

16) Киргизүү чек-тизмеси

• Бирдиктүү 'problem + json' + туруктуу 'error _ code'.
• Туура семантика HTTP/gRPC/GraphQL.
• Retriable/non-retriable + 'Retry-After '/back-off сунуштар.
• Rate-limit аталыштары жана 429 жүрүм-туруму.
• Idempotency ('Idempotency-Key', 409/412).
• Коопсуздук: stack traces/сырлары жок, PII редакциясы.
• 'trace _ id '/' X-Request-ID' бардык каталарда.
• Каталар каталогунун документтери жана мисалдар.
• Каталардын таксономиясы боюнча мониторинг.
• Автотесттер терс сценарийлер.

17) Mini-FAQ

400 422 эмнеси менен айырмаланат?
400 - сынган суроо (синтаксис/мазмундун түрү). 422 - синтаксис боюнча валиддик, бирок бизнес эрежелери өткөн жок.

Качан 401, качан 403?
401 - жок/туура эмес токен; 403 - токен бар, укуктар жетишсиз.

Ар дайым 'Retry-After' керек?
429/503 үчүн - ооба; башка retriable үчүн - ачык сунуш берүү максатка ылайыктуу.

Жыйынтык

Жакшы долбоорлонгон каталар - бул келишим: туура HTTP статусу, бирдиктүү 'problem + json', туруктуу 'error _ code', ретрага боюнча ачык-айкын кеңештер жана катуу коопсуздук. Форматты стандартташтыруу, таксономияны документтештирүү, телеметрия жана тесттерди кошуу - жана сиздин API интеграторлорго болжолдуу, коопсуз жана достук болот.