Термины API: endpoint, payload, idempotent, rate limit, deprecate

Тема дорожной карты · Английский для IT

🔊 Словарь терминов с произношением →

Словарь API — это словарь HTTP, дополненный терминами контрактов и жизненного цикла. Endpoint — конечная точка, конкретный URL с методом: GET /users/{id}. Resource — ресурс, сущность за URL. Route — маршрут в коде, path parameter (/users/{id}), query parameter (?limit=50), header, body. Payload — полезная нагрузка, содержимое тела запроса или ответа. Request / response, status code: 2xx успех, 3xx перенаправление, 4xx ошибка клиента, 5xx ошибка сервера; 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized (на самом деле «не аутентифицирован»), 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout. Методы: GET, POST, PUT (полная замена), PATCH (частичное обновление), DELETE. Idempotent — идемпотентный: повторный вызов даёт тот же результат (GET, PUT, DELETE идемпотентны, POST нет); idempotency key — ключ, делающий POST безопасным для повтора. Safe method — не меняет состояние. Rate limit — ограничение частоты, to be rate-limited, quota, throttling, backoff — увеличение паузы между повторами, exponential backoff with jitter. Retry — повтор, retryable, timeout. Pagination — постраничный вывод: offset / limit, cursor-based, next page token. Versioning — версионирование: /v1/, header-based. Deprecate — объявить устаревшим, deprecated, sunset — дата отключения, breaking change, backward compatible — обратно совместимый. Contract — контракт API, schema, OpenAPI / Swagger, spec. Authentication (кто вы) и authorization (что можно): token, bearer token, API key, OAuth, scope, refresh token, expired. Webhook — обратный вызов по событию. Polling — опрос. Long polling, SSE, WebSocket. Serialize / deserialize, marshal / unmarshal (Go). Validation — валидация, malformed — некорректно сформированный. Latency, p50 / p95 / p99 — перцентили. Mock, stub, sandbox — тестовое окружение API. SDK, client library. CORS. Content negotiation, content type. Upstream / downstream service. Graceful degradation, fallback, circuit breaker.

Как произносится

Endpoint /ˈɛndpɔɪnt/, payload /ˈpeɪloʊd/, idempotent /ˌaɪdɛmˈpoʊtənt/, idempotency /ˌaɪdɛmˈpoʊtənsi/, rate limit /reɪt ˈlɪmɪt/, throttle /ˈθrɒtl/, backoff /ˈbækɒf/, jitter /ˈdʒɪtər/, deprecate /ˈdɛprəkeɪt/ (ударение на первый слог), deprecated /ˈdɛprəkeɪtɪd/, sunset /ˈsʌnsɛt/, pagination /ˌpædʒɪˈneɪʃən/ («пэджинЕйшен»), cursor /ˈkɜːrsər/, authentication /ɔːˌθɛntɪˈkeɪʃən/, authorization /ˌɔːθəraɪˈzeɪʃən/, bearer /ˈbɛərər/ («бЭрэр»), OAuth «оу-ос», webhook /ˈwɛbhʊk/, polling /ˈpoʊlɪŋ/ (как pole, не как pull), serialize /ˈsɪəriəlaɪz/, malformed /ˌmælˈfɔːrmd/, percentile /pərˈsɛntaɪl/, schema /ˈskiːmə/, CORS /kɔːrz/ как слово, JSON /ˈdʒeɪsən/, REST /rɛst/, GraphQL «граф-кью-эль», gRPC «джи-ар-пи-си».

Как употребляется

  • Make the endpoint idempotent: accept an idempotency key and dedupe on it. — Сделай эндпоинт идемпотентным: принимай ключ идемпотентности и дедуплицируй по нему.
  • We're getting 429s; back off exponentially and add jitter. — Ловим 429, увеличивай паузу экспоненциально и добавь разброс.
  • The payload is too large; paginate with a cursor instead of offset. — Ответ слишком большой, пагинируй курсором вместо offset.
  • This field is deprecated and will be sunset on March 1st. — Поле устарело и будет отключено 1 марта.
  • 401 means the token is missing or expired; 403 means you're authenticated but not allowed. — 401: токена нет или он истёк; 403: вы аутентифицированы, но не имеете прав.
  • The upstream timed out, so we returned a 504. — Апстрим не ответил вовремя, вернули 504.
  • p99 latency on the search endpoint is 1.2 seconds. — p99-задержка поиска 1,2 секунды.

Ловушки

Первая ловушка — deprecated как «удалённый»: устаревшее ещё работает, но будет удалено; removed — уже нет. Вторая — 401 Unauthorized понимать буквально: это ошибка аутентификации, а ошибка авторизации — 403. Третья — authentication и authorization как синонимы: «кто вы» и «что вам можно». Четвёртая — idempotent с ударением на «дем» и как «безопасный»: GET безопасен и идемпотентен, DELETE идемпотентен, но не безопасен. Пятая — polling произносить как pulling: /ˈpoʊlɪŋ/. Шестая — rate limit переводить как «лимит скорости»: это ограничение частоты запросов. Седьмая — sunset как «закат»: в API это дата окончания поддержки, есть даже HTTP-заголовок Sunset.

Связанные понятия

Полезные ресурсы