Схемы остаточных API-интерфейсов

Question

Я новичок в использовании API REST, но я видел, что многие системы, которые предоставляют API REST, не предоставляют схему (структуру) сообщения, которое будет возвращено. Из-за этого мы не можем быть уверены в том, как точно анализировать ответ. Например, вызов API сегодня может возвращать определенный набор полей, и позже в какой-то момент они могут захотеть добавить в ответ другое поле, которое может испортить мой парсер. Итак, если я должен разобрать ответное сообщение о конкретном вызове, как я могу сделать это правильно? Как системы, которые выставляют эти API, обрабатывают вызовы внутренне?

Answer 1

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

Это может случиться практически с любой библиотекой, в которой вы используете не только API REST.

Обычное соглашение заключается в том, что ваша нумерация версий в формате Major.minor.patch (см. http://semver.org/). Все, что нарушает обратную совместимость, должно иметь основной номер версии. Конечно, не все сопровождающие следуют этому примеру, следуйте за ним, если ваш провайдер (ы), у которого вы потребляете API, является плохим в этом, вы не можете много сделать.

Что вы можете сделать, это убедиться, что вы реализуете и управление версиями зависимостей для всех библиотек, включая ваш API, ну, знаем, какую версию вы хотите поддержать использование explict версий на основе вызовов вместо

http://example.com/api/customers/1234 

использование

http://example.com/api/v3.0/customers/1234 

и следить за зависимостями для вашего проекта, а также следить за документацией поставщика обновлений, увидеть, если это будет влиять на вас в Анвэй

Что касается API, который находится в схематичных форматах, в то время как новые поля могут не создавать проблем, удаление существующих или изменение представления, логика и т. Д. Нарушит ваш код способами, которые трудно отлаживать, изменения могут быть тонкими.

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

Answer 2

Многие службы REST используют JSON в качестве базового формата для кодирования данных. Клиенты должны просто игнорировать свойства, которые они не знают в ответе JSON, тем самым позволяя серверу развивать свой вывод с течением времени (учитывая, что сервер не переименовывает или не удаляет свойства). Управление версиями службы REST - это отдельная дискуссия (попробуйте найти ее).

Итак, вкратце - новые поля не должны испортить ваш синтаксический анализатор, он должен просто игнорировать их.

Answer 3

Хорошо, самые хорошие делают! см., например, - OpenStack REST API. Кроме того, обратите внимание, что ответ возвращается для этой конкретной версии API, то есть, если вы используете API (скажем):

/api/v1.0/interfaces/interface 

и вы можете получить некоторые поля, как:

{ "name : "eth0", "ip" : "10.1.1.1" } 

Теперь API может развиваться, и может быть версия 1.1, которая добавляет несколько полей (сохраняя обратную совместимость). То есть, /api/v1.1/interfaces/interface может вернуться:

{ "name : "eth0", "ip" : "10.1.1.1" , "mtu" : 1500 } 

или 2.0, который имеет совершенно иную структуру, нарушая обратную совместимость:

GET /api/v2.0/interfaces/interface 
... 
{ "interface" : { "name : "eth0", "ip" : "10.1.1.1" , "mtu" : 1500 }} 

снова, все они должны быть хорошо документированы!

И код с использованием API, должен знать о версиях, в которых они заинтересованы, и соответствующим образом анализировать ответ.

Формат ответа, кстати, зависит от вида запроса вы делаете, в течение, например, если вы С.Е. Accept-кодирование в формате JSON (Accept: application/json), возвращаемый ответ должен быть в формате JSON - так что вы знаете, какие парсер для использования.

НТН