Спецификация проекта RESETful API для небольших команд

В статье говорится о наиболее распространенныхRESETful APIДизайн и документация не обязательно идеальны, если есть какие-либо упущения или неточности, пожалуйста, смиритесь с ними и сделайте замечания.

Об использовании «желательных глаголов»

Во избежание двусмысленности в документе используется много «желательных глаголов», и соответствующие пояснения выглядят следующим образом:

必须 (MUST): абсолютно, строго следовать, пожалуйста, следовать, безоговорочно следовать;
一定不可 (MUST NOT): запрет, строго запретить;
应该 (SHOULD): Это настоятельно рекомендуется, но не обязательно;
不该 (SHOULD NOT): Это настоятельно не рекомендуется, но не обязательно;
可以 (MAY)а также可选 (OPTIONAL): немного более избирательно, в этом документе этот термин используется реже;

Ссылаться наRFCДокументация

Status of this Memo

   This document specifies an Internet Best Current Practices for the
   Internet Community, and requests discussion and suggestions for
   improvements.  Distribution of this memo is unlimited.

Abstract

   In many standards track documents several words are used to signify
   the requirements in the specification.  These words are often
   capitalized.  This document defines these words as they should be
   interpreted in IETF documents.  Authors who follow these guidelines
   should incorporate this phrase near the beginning of their document:

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
      "OPTIONAL" in this document are to be interpreted as described in
      RFC 2119.

   Note that the force of these words is modified by the requirement
   level of the document in which they are used.

1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that the
   definition is an absolute requirement of the specification.

2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
   definition is an absolute prohibition of the specification.

3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
   may exist valid reasons in particular circumstances to ignore a
   particular item, but the full implications must be understood and
   carefully weighed before choosing a different course.

4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
   there may exist valid reasons in particular circumstances when the
   particular behavior is acceptable or even useful, but the full
   implications should be understood and the case carefully weighed
   before implementing any behavior described with this label.

Protocol

клиент черезAPIВо время связи с серверными службами应该использоватьHTTPSпротокол.

API Root URL

APIКорневая точка входа должна быть как можно более простой, вот две наиболее распространенные.URLПример корня:

api.example.com/*
example.com/api/*

Если ваше приложение огромно или вы ожидаете, что он будет огромным, то应该БудуAPIпоместите его в поддомен (api.example.com). Такой подход сохраняет некоторую гибкость при масштабировании.

Versioning

всеAPIдолжны оставаться обратно совместимыми, вы必须Представляем новую версиюAPIпри обеспечении более старых версийAPIдо сих пор доступен. так应该Обеспечить поддержку версии для него.

Есть две распространенные версии номеров версий:

Вставить номер версии в URL

api.example.com/v1/*

Этот подход делает номер версии интуитивно понятным и простым для отладки; другой подход заключается в том, чтобы указать номер версии вHTTP HeaderВ голове:

Укажите информацию о версии по типу носителя

Accept: application/vnd.example.com.v1+json

вvndвыражатьStandards TreeСтандартный тип дерева, есть три разных дерева:x,prsа такжеvnd. Стандартное дерево, которое вы используете, должно зависеть от проекта, который вы разрабатываете.

незарегистрированное дерево (x) в основном для локальных и частных сред
частное дерево (prs) в основном указывает на элементы, которые не имеют коммерческого выпуска
Дерево поставщиков (vnd) в основном указывает на общедоступный элемент

Следующие параметры — это имя приложения (обычно имя домена приложения), номер версии и ожидаемый формат возврата.

Было много споров о том, где именно указать номер версии, но поскольку мы используем его большую часть времениLaravelразвивать,应该использоватьdingo/apiдля быстрой сборки приложений используется второй способ управленияAPIверсия, и интегрировал стандартHTTP Response.

Endpoints

Конечная точка — это точка, которая указывает на конкретный ресурс или набор ресурсов.URL. При проектировании конечной точки вы必须Придерживайтесь следующих соглашений:

Именование URL-адресов必须все строчные
Ресурс в URL (resource) именование必须это существительное и必须во множественном числе
必须Приоритетное использованиеRestfulтип URL-адреса
URL 必须разборчиво
URL 一定不可Раскрыть серверную архитектуру

Что касается того, должны ли URL-адреса использовать дефисы (-) или подчеркивание (_), нет жесткого правила, но必须Объедините стиль в соответствии с ситуацией в команде.

Давайте посмотрим встречный пример

API.example.com/получить информацию о пользователе…
api.example.com/getusers
api.example.com/sv/u
API.example.com/cgi-bin/use…

Давайте посмотрим еще один столбец

api.example.com/zoos
api.example.com/animals
API.example.com/zoos/{zoo}/…
API.example.com/animal_type…
api.example.com/employees

HTTP-глаголы

Для конкретного типа работы ресурса,HTTPглагол выражает. общийHTTPЕсть следующие пять глаголов (соответствующие в скобкахSQLЗаказ).

ПОЛУЧИТЬ (ВЫБРАТЬ): получить ресурсы с сервера.
POST (CREATE): Создайте новый ресурс на сервере.
PUT (UPDATE): обновить ресурс на сервере (клиент предоставляет полный ресурс после изменения).
ИСПРАВЛЕНИЕ (ОБНОВЛЕНИЕ): Обновите ресурс на сервере (клиент предоставляет измененные свойства).
УДАЛИТЬ (DELETE): Удаляет ресурс с сервера.

1 удалить ресурс必须использоватьDELETEСпособ 2 Создать новый ресурс必须использоватьPOSTСпособ 3 Обновить ресурсы应该использоватьPUTМетод 4 Получить информацию о ресурсах必须использоватьGETметод

Для каждой конечной точки в следующем списке перечислены все возможныеHTTPКомбинации глаголов и конечных точек

метод запроса	URL	описывать
GET	/zoos	Перечислите все зоопарки (идентификаторы и названия, не вдавайтесь в подробности)
POST	/zoos	Добавить новый зоопарк
GET	/zoos/{zoo}	Получите подробную информацию о назначенном зоопарке
PUT	/zoos/{zoo}	обновить указанный зоопарк (весь объект)
PATCH	/zoos/{zoo}	обновить зоопарк (частичный объект)
DELETE	/zoos/{zoo}	удалить указанный зоопарк
GET	/zoos/{zoo}/animals	Получить список животных в указанном зоопарке (ID и имя, не слишком подробные)
GET	/animals	Перечислите всех животных (идентификатор и имя).
POST	/animals	Добавить новых животных
GET	/animals/{animal}	Получить указанные данные о животных
PUT	/animals/{animal}	Обновляет указанное животное (весь объект)
PATCH	/animals/{animal}	Обновить указанное животное (часть объекта)
GET	/animal_types	Получите все типы животных (идентификаторы и имена, не слишком подробно)
GET	/animal_types/{type}	Получить сведения об указанном типе животных
GET	/employees	Получить весь список сотрудников
GET	/employees/{employee}	Получить конкретного сотрудника
GET	/zoos/{zoo}/employees	Получить список сотрудников, работающих в этом зоопарке (идентификаторы и имена)
POST	/employees	Добавить назначенных новых сотрудников
POST	/zoos/{zoo}/employees	Нанять сотрудника в конкретный зоопарк
DELETE	/zoos/{zoo}/employees/{employee}	Уволить работника из зоопарка

внеRestfulКонечная точка,应该Определите конечные точки так, как показано в таблице выше.

Filtering

Если количество записей велико, сервер не может вернуть их все пользователю. API应该Укажите параметры для фильтрации возвращаемых результатов. Ниже приведены некоторые общие параметры.

?limit=10: Укажите количество возвращаемых записей.
?offset=10: указывает начальную позицию возвращаемой записи.
?page=2&rows0: укажите количество страниц и количество записей на странице.
?order_by=me&order=asc: указывает, по какому атрибуту возвращаемые результаты сортируются, и порядок сортировки.
?animal_type_id=1: Укажите критерии фильтра

всеURLпараметр必须все в нижнем регистре,必须Используйте форму параметра типа подчеркивания.

параметры пагинации必须исправлено какpage,rows

Часто используемые, сложные запросы应该Маркировка снижает затраты на техническое обслуживание. Такие как

GET /trades?status=closed&order_by=name&order=asc

# 可为其定制快捷方式
GET /trades/recently_closed

Authentication

应该использоватьOAuth2.0способ обеспечить аутентификацию входа для вызывающих API.必须Сначала пройдите через интерфейс входаAccess Tokenзатем пройтиtokenВызовы, требующие аутентификацииAPI.

Пример дизайна конечной точки для Oauth

RFC 6749 /token
Twitter /oauth2/token
Fackbook /oauth/access_token
Google /o/oauth2/token
Github /login/oauth/access_token
Instagram /oauth/authorize

клиент получаетaccess tokenтем временем必须Включите в ответ aexpires_inданные, которые представляют собой полученные в настоящее времяtokenсколько это будет秒позже недействительно.

{
    "access_token": "token....",
    "token_type": "Bearer",
    "expires_in": 3600
}

Клиент запрашивает аутентификациюAPIчас,必须в заголовке запросаAuthorizationремень наaccess_token.

Authorization: Bearer token...

Через указанное количество секундaccess tokenистечет, используйте просроченный/или недействительный сноваtokenПри доступе сервер应该вернутьinvalid_tokenошибка или401код ошибки.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "error": "invalid_token"
}

В разработке,应该использоватьJWTдля управления вашими токенами и一定不可существуетapiОткрытый запрос в промежуточном программном обеспеченииsession.

Response

всеAPIотклик,必须подчинятьсяHTTPСпецификация проекта,必须выбрать правильныйHTTPкод состояния.一定不可Все интерфейсы возвращают код состояния как200изHTTPответ типа:

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "code": 0,
    "msg": "success",
    "data": {
        "username": "username"
    }
}

или

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "code": -1,
    "msg": "该活动不存在",
}

В следующей таблице перечислены общиеHTTPкод состояния

код состояния	описывать
1xx	От имени запрос принят и нуждается в продолжении обработки
2xx	Запрос был выполнен успешно, и заголовки ответа или тела данных, ожидаемые запросом, будут возвращены с этим ответом.
3xx	перенаправить
4xx	Ошибка вызвана клиентом
5xx	Ошибки, вызванные причинами на стороне сервера

Возврат только после того, как запрос от клиента был правильно обработан2xxответ, поэтому, когда API возвращает2xxтип кода состояния, когда внешний интерфейс必须Определение того, что запрос был успешно обработан

Необходимо подчеркнуть, что всеAPI 一定不可вернуть1xxТип кода состояния. когдаAPIКогда возникает ошибка,必须Возвращает подробную информацию об ошибке. В настоящее время существует два распространенных способа возврата информации об ошибке:

1. Поместите сведения об ошибке вHTTPзаголовок ответа;

X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication

2. Поместите его непосредственно в объект ответа;

HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive

{"error_code":40100,"message":"Unauthorized"}

Учитывая удобочитаемость и удобочитаемость на стороне клиента, мы必须Поместите информацию об ошибке непосредственно в объект ответа, а неправильный формат应该Встречайте следующий формат:

{
    "message": "您查找的资源不存在",
    "error_code": 404001
}

где код ошибки(error_code)必须а такжеHTTPСоответствующие коды состояния также удобны для классификации кодов ошибок, таких как:

HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:15:52 GMT
Connection: keep-alive

{"error_code":429001,"message":"你操作太频繁了"}

应该Возвращаемое сообщение об ошибке включает как ориентированную на разработчика, так и ориентированную на пользователя подсказку. Первая удобна для отладки разработчиками, а вторая может быть напрямую отображена для просмотра конечными пользователями, например:

{
    "message": "直接展示给终端用户的错误信息",
    "error_code": "业务错误码",
    "error": "供开发者查看的错误信息",
    "debug": [
        "错误堆栈，必须开启 debug 才存在"
    ]
}

Ниже приведен подробный список описаний возврата API для каждой ситуации.

200 ok

200Коды состояния являются наиболее распространенными.HTTPкод состояния, всегоуспехизGETзапрос,必须Верните этот код состояния.HTTPЧасть объекта ответа必须Это непосредственно данные, не делайте избыточной упаковки.

Пример ошибки:

HTTP/1.1 200 ok
Content-Type: application/json
Server: example.com

{
    "user": {
        "id":1,
        "nickname":"fwest",
        "username": "example"
    }
}

Правильный пример:

1. Получите подробную информацию об одном ресурсе

{
    "id": 1,
    "username": "godruoyi",
    "age": 88,
}

2. Соберите коллекцию ресурсов

[
    {
        "id": 1,
        "username": "godruoyi",
        "age": 88,
    },
    {
        "id": 2,
        "username": "foo",
        "age": 88,
    }
]

3. Дополнительная информация о носителе

{
    "data": [
        {
            "id": 1,
            "avatar": "https://lorempixel.com/640/480/?32556",
            "nickname": "fwest",
            "last_logined_time": "2018-05-29 04:56:43",
            "has_registed": true
        },
        {
            "id": 2,
            "avatar": "https://lorempixel.com/640/480/?86144",
            "nickname": "zschowalter",
            "last_logined_time": "2018-06-16 15:18:34",
            "has_registed": true
        }
    ],
    "meta": {
        "pagination": {
            "total": 101,
            "count": 2,
            "per_page": 2,
            "current_page": 1,
            "total_pages": 51,
            "links": {
                "next": "http://api.example.com?page=2"
            }
        }
    }
}

Среди них, пейджинг и другие дополнительные медиа-информации, должны быть размещеныmetaв поле.

201 Created

Когда сервер успешно создает данные,应该Верните этот код состояния. Обычный сценарий применения заключается в использованииPOSTОтправьте информацию о пользователе, такую как:

Добавлен новый пользователь
загруженное изображение
Создано новое событие

подожди, ты можешь вернуться201код состояния. Следует отметить, что вы можете выбрать возврат данных нового пользователя после его успешного создания.

HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:13:40 GMT
Connection: keep-alive

{
    "id": 1,
    "avatar": "https:\/\/lorempixel.com\/640\/480\/?32556",
    "nickname": "fwest",
    "last_logined_time": "2018-05-29 04:56:43",
    "created_at": "2018-06-16 17:55:55",
    "updated_at": "2018-06-16 17:55:55"
}

Также возможно вернуть объект ответа с пустымHTTP ResponseТакие как:

HTTP/1.1 201 Created
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:12:20 GMT
Connection: keep-alive

мы тут应该Принят второй метод, потому что в большинстве случаев клиенту нужно только знать, успешна ли операция запроса, и ему не нужно возвращать информацию о новом ресурсе.

202 Accepted

Этот код состояния указывает на то, что сервер принял запрос от клиента, но еще не начал его обработку. Обычно используется в таких сценариях, как отправка SMS, уведомление по электронной почте, отправка шаблонного сообщения и т. д., которые отнимают много времени и требуют поддержки очереди;

Когда этот код состояния возвращается, объект ответа必须Пусто.

HTTP/1.1 202 Accepted
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:25:15 GMT
Connection: keep-alive

204 No Content

Этот код состояния указывает, что объект ответа не содержит данных, где:

В использованииDELETEметод удаления ресурсауспехчас,必须вернуть этот код состояния
использоватьPUT,PATCHметод обновления данныхуспехкогда тоже应该вернуть этот код состояния

HTTP/1.1 204 No Content
Server: nginx/1.11.9
Date: Sun, 24 Jun 2018 09:29:12 GMT
Connection: keep-alive

3xx редирект

всеAPI 不该вернуть3xxТип кода состояния. потому что3xxФормат ответа типа обычно имеет следующий формат:

HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 09:41:50 GMT
Location: https://example.com
Connection: keep-alive

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta http-equiv="refresh" content="0;url=https://example.com" />

        <title>Redirecting to https://example.com</title>
    </head>
    <body>
        Redirecting to <a href="https://example.com">https://example.com</a>.
    </body>
</html>

всеAPI 一定不可вернуть чистымHTMLСтруктурированный ответ; если вы должны использовать функцию перенаправления,可以Возвращает объект ответа с пустым3xxответ и добавьте его в заголовок ответаLocationПоле:

HTTP/1.1 302 Found
Server: nginx/1.11.9
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 24 Jun 2018 09:52:50 GMT
Location: https://godruoyi.com
Connection: keep-alive

400 Bad Request

Из-за очевидных ошибок клиента (например, неверный синтаксис запроса, неверный запрос, неверная подпись и т. д.) сервер应该Отказаться от запроса.

Когда сервер не может найти подходящий тип ошибки среди других кодов состояния 4xx, он必须Верните этот код состояния.

HTTP/1.1 400 Bad Request
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:22:36 GMT
Connection: keep-alive

{"error_code":40000,"message":"无效的签名"}

401 Unauthorized

Этот код состояния указывает, что текущий запрос требует аутентификации в следующих случаях.必须Верните этот код состояния.

Пользователи, не прошедшие проверку подлинности, получают доступ к API, требующим проверки подлинности.
access_token недействителен/истек.

клиент получает401После ответа оба应该Запросите у пользователя следующую операцию входа в систему.

HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
WWW-Authenticate: JWTAuth
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:17:02 GMT
Connection: keep-alive

{"message":"Token Signature could not be verified.","error_code": "40100"}

403 Forbidden

Код состояния можно просто понять как нет доступа к запросу, сервер получает запрос, но отказался предоставлять услуги.

Например, когда обычный пользователь запрашивает управление пользователем-администратором,必须Верните этот код состояния.

HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 13:05:34 GMT
Connection: keep-alive

{"error_code":40301,"message":"权限不足"}

404 Not Found

Этот код состояния указывает, что ресурс, запрошенный пользователем, не существует, например

Получить информацию о несуществующем пользователе (получить /users/9999999)
Доступ к несуществующим конечным точкам

Все必须Возвращает этот код состояния, если ресурс никогда не существовал, то应该вернуть410отклик.

405 Method Not Allowed

когда клиент используетHTTPКогда метод запроса не разрешен сервером,必须Верните этот код состояния.

Если клиент звонитPOSTметод для доступа к API, которые поддерживают только метод GET

Ответ必须вернутьAllowИнформация заголовка используется для указания списка методов запроса, которые может принять текущий ресурс.

HTTP/1.1 405 Method Not Allowed
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Allow: GET, HEAD
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:30:57 GMT
Connection: keep-alive

{"message":"405 Method Not Allowed","error_code": 40500}

406 Not Acceptable

APIЭтот код состояния должен быть возвращен, если формат данных, указанный клиентом, не поддерживается. как поддерживаетсяJSONа такжеXMLвыходAPIпредназначен для возвращенияYAMLКогда формат данных.

Протокол Http обычно указывает формат данных через Accept в заголовке запроса.

408 Request Timeout

Когда время запроса клиента истекает必须Возвращает код состояния.Когда необходимо обратить внимание, код состояния указывает, чтоВремя запроса клиента истекло, где участвует третья сторонаAPIКогда время вызова истекает,一定不可Верните этот код состояния.

409 Confilct

Этот код состояния указывает, что запрос не может быть обработан из-за конфликта. Если предусмотрена функция регистрации через номер мобильного телефонаAPI, когда номер мобильного телефона, отправленный пользователем, уже существует,必须Верните этот код состояния.

HTTP/1.1 409 Conflict
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:19:04 GMT
Connection: keep-alive

{"error_code":40900,"message":"手机号已存在"}

410 Gone

а также404Точно так же этот код состояния также указывает, что запрошенный ресурс не существует, только410Код состояния также указывает, что запрошенный ресурс больше не существует и не будет существовать в будущем. при получении410После кода состояния клиент应该Прекратите снова запрашивать ресурс.

413 Request Entity Too Large

Этот код состояния указывает, что сервер отказывается обрабатывать текущий запрос, так как размер данных сущности, отправленных запросом, превышает диапазон, который сервер хочет или может обработать.

В этом случае сервер МОЖЕТ закрыть соединение, чтобы клиент не мог продолжать отправлять этот запрос.

Если это состояние временное, сервер应该вернутьRetry-Afterзаголовок ответа, чтобы сообщить клиенту, сколько позже он может повторить попытку.

414 Request-URI Too Long

Этот код состояния указывает, что запрошенныйURIДлина больше, чем может интерпретировать сервер, поэтому сервер отказывается обслуживать запрос.

415 Unsupported Media Type

Обычно указывает, что сервер не поддерживает заголовки клиентских запросов.Content-TypeУказанный формат данных. Если только принятьJSONформатированныйAPIвставитьXMLтип данных и отправить их на сервер, как应该Верните этот код состояния.

Этот код состояния также можно использовать, например: разрешено загружать только файлы в формате изображения, но медиафайлы, отправленные клиентом, являются незаконными или не относятся к типу изображения.应该Верните этот код состояния:

HTTP/1.1 415 Unsupported Media Type
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 12:09:40 GMT
Connection: keep-alive

{"error_code":41500,"message":"不允许上传的图片格式"}

429 Too Many Requests

Этот код состояния указывает, что количество пользовательских запросов превышает допустимый диапазон. Такие какAPIустановить как60次/分钟, когда пользователь запрашивает более 60 раз в минуту,应该Верните этот код состояния. а также应该Добавьте следующие заголовки в заголовки ответа:

X-RateLimit-Limit: 10 请求速率（由应用设定，其单位一般为小时/分钟等，这里是 10次/5分钟）
X-RateLimit-Remaining: 0 当前剩余的请求数量
X-RateLimit-Reset: 1529839462 重置时间
Retry-After: 120 下一次访问应该等待的时间（秒）

Льези

HTTP/1.1 429 Too Many Requests
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1529839462
Retry-After: 290
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 11:19:32 GMT
Connection: keep-alive

{"message":"You have exceeded your rate limit.","error_code":42900}

必须Установить поддержку ограничения скорости для всех API.

500 Internal Server Error

код состояния必须Выброшено при ошибке сервера, для всех500ошибка, оба应该Обеспечьте полную поддержку информации об ошибках, а также облегчите отслеживание и отладку.

503 Service Unavailable

Этот код состояния указывает на то, что сервер временно находится в недоступном состоянии, когда сервер нуждается в обслуживании или в третьей стороне.APIКогда время запроса истекло/недоступно, оба应该Возвращает этот код состояния, в котором, если служба API активно закрыта,应该Добавить в возвращаемый заголовок ответаRetry-AfterЗаголовок, указывающий, через сколько секунд снова получить доступ.

HTTP/1.1 503 Service Unavailable
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:56:20 GMT
Retry-After: 60
Connection: keep-alive

{"error_code":50300,"message":"服务维护中"}

разноеHTTPПожалуйста, обратитесь к коду состоянияКоды состояния HTTP — Википедия.