[Паттерны API] Частичные обновления. Деградация и предсказуемость

Главу 24 как будто бы хочется разделить на две, потому что она фактически описывает решение двух разных проблем - как частично обновлять ресурсы, и как управлять вложенными в ресурс списками.

По первому вопросу, можно было бы упомянуть ещё третий вариант сообщения о том, какие поля изменились, а какие нет. Он идёт из гугловских конвенций про gRPC.

Там есть стандартная конструкция FieldMask, которая несёт в себе набор полей, потенциально вложенных. Как правило, по конвенции филд-маска обязательно включается в READ-запросы, но и в UPDATE-запросы.

Например, будет так:

updateOrder {
  "id": "1",
  "payload": {
    "estimated_delivery_at": "2023-01-01T12:00:00Z",
    "delivery_address": { "street": "New St." }
  },
  "update_field_mask": {
    "paths": [
      "estimated_delivery_at",
      "delivery_address.street"
    ]
  },
  "field_mask": { 
    "paths": [
      "id",
      "estimated_delivery_at",
      "delivery_address.street",
      "delivery_address.house_number",
      "delivery_address.zip"
    ]
  }
}

Где update_field_mask показывает, какие поля следует обновить, а field_mask управляет теми полями, которые клиент ожидает в ответе.

Ествественно, это всё обвязано конвенциями и неким простым стандартным тулингом.

По практике, получается прямо очень удобно. Выглядит странно, но решает проблемы:

1. over/under-фетчинга: обработчик может не делать какие-то под-запросы, если клиент не запрашивает какие-то поля.

2. Backwards compatibility (если следовать остальным политикам по этой теме) - клиент оперирует только теми данными, которые запрашивает, и его не волнует, как дальше эволюционирует сама сущность.