Какова стандартная практика проектирования REST API, если он используется для вставки / обновления списка записей? - PullRequest
Новая
       18

Какова стандартная практика проектирования REST API, если он используется для вставки / обновления списка записей?

0 голосов
/ 25 января 2019

Мы создаем API, который будет использоваться для вставки и обновления записей в базе данных.Поэтому, если запись существует на основе ключа, запись будет обновлена, а если нет, то она будет вставлена.

У меня есть два вопроса.

  • Согласно рекомендациям REST,Какие есть варианты для разработки такого API, например, PUT / POST OR PATCH?Как должен быть представлен список объектов?ПРИМЕЧАНИЕ: я знаю из других ответов, которые я прочитал, что существует путаница в том, как это должно быть в соответствии с рекомендациями REST.Так что я в порядке, если смогу получить некоторые рекомендации по общей наилучшей практике (независимо от части REST) ​​
  • Во-вторых, часть, в которой я действительно запутался, состоит в том, как представить выходные данные этого или что должен возвращать этот API.

Буду признателен за конкретные рекомендации / материалы по вышеуказанной теме.

1 Ответ

0 голосов
/ 25 января 2019

Я видел много разных реализаций для вставок / обновлений у разных поставщиков (Stripe, HubSpot, PayPal, Google, Microsoft).Несмотря на то, что они различаются, разница как-то хорошо согласуется с их общей реализацией API и, как правило, не является причиной стресса.

С учетом вышесказанного, "общее" правило для вставок is:

POST /customers - предоставьте данные клиента в пределах body.

. Это создаст нового клиента, вернет уникальный идентификатор и данные клиента в ответе (вместе с * 1012).* и другие автоматически сгенерированные атрибуты).

Практически все, если не все поставщики API, реализуют эту логику для вставок.

Обновления вполнеразные.Возможны следующие варианты:

POST

POST /customer/<customer_id> - включает атрибуты и значения, которые вы хотите обновить в теле.

Здесь вы используете POST чтобы обновить клиента.Это не очень распространенная реализация, но я видел ее в нескольких местах.

PUT

PUT/customer/<customer_id> - включать в себя все или частично обновленные атрибуты вbody.

С технической точки зрения PUT является идемпотентным методом, вы можете либо остаться верным соглашению REST и ожидать, что ваши пользователи предоставят все атрибуты для обновления ресурса, либо упростить его, принимая только атрибуты.они хотят обновить.Второй вариант не очень «RESTful», но его легче обрабатывать с точки зрения пользователей (и уменьшает размер полезной нагрузки).

PATCH

PATCH /customer/<customer_id> - включите операцию и атрибуты, которые вы хотите обновить / удалить / заменить / и т.д. в теле.Подробнее о том, как PATCH .

Метод PATCH используется для частичных обновлений, и именно так вы «должны» вызывать частичные обновления.Это немного сложнее в использовании с точки зрения потребителя.

Теперь, это смещение.Я лично предпочитаю использовать POST, где я не обязан предоставлять все атрибуты для вызова обновления (только те, которые я хочу обновить).Причина заключается в простоте использования.

С точки зрения тела ответа для обновлений обычно они возвращают объект в теле ответа, включающий обновленные атрибуты (и обновленные автоматически сгенерированные атрибуты, такие как updatedDate)..

Массовые вставки / обновления

Глядя на Facebook Graph HTTP API (Пакетный запрос) для вдохновения и предполагая POST ваш предпочтительный способ обновления, вы можете встроить массив запросов, используя выделенный ресурс batch в качестве опции.

Конечная точка : POST /batch/customers

Тело : 

{
   ["first_name": "John", "last_name": "Smith"...], //CREATE
   ["id": "777", "first_name": "Jane", "last_name": "Doe"...], //UPDATE
   ["id": "999", "first_name": "Mike", "last_name": "Smith"...], //UPDATE
   [....]
}

Пример ответа 

{
  "id": "123",
  "result":[
      { // Creation successful
        "code": 200,
        "headers":{..},
        "body": {..},
        "uri": "/customers/345"
      },
      { // Update successful
        "code": 200,
        "headers":{..},
        "body": {..},
        "uri": "/customers/777",
      },
      { // A failed update request
        "code": 404,
        "headers":{..},
        "body": {..}, // body includes error details
      }
  ]
}
...