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

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

При этом «общее» правило для вставок таково:

POST /customers - укажите данные клиента в body.

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

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

Обновления совсем другие. Ваши варианты включают в себя:

РАЗМЕСТИТЬ

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

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

ВСТАВИТЬ

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

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

ИСПРАВЛЕНИЕ

PATCH /customer/<customer_id> — включает операцию и атрибуты, которые вы хотите обновить/удалить/заменить/и т. д. в теле. Подробнее о том, как ИСПРАВИТЬ .

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

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

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

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

Глядя на API Facebook Graph HTTP (пакетный запрос) для вдохновения, и предполагая, что 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
      }
  ]
}