День 1633. #ЗаметкиНаПолях
Разработка API для Людей.
Часть 3. Принципы разработки. Окончание
Начало
Часть 1
Часть 2
Раннее определение принципов разработки открывает ряд огромных преимуществ, которые помогут увеличить долговечность и скорость разработки вашего API.
1. Будьте последовательны
Наиболее распространёнными операциями для API являются запрос на получение ресурса (GET) и на создание или обновление ресурса (POST).
// Создание продукта
POST /v1/products
// Обновление продукта
POST /v1/products/:id
// Получение продукта
GET /v1/products/:id
В примере выше маршрут для получения продукта позволяет получать только один продукт за раз. Это довольно неудобно. Добавление конечной точки для получения списка продуктов предоставит пользователю гибкость и возможность сократить количество запросов к API:
// Получаем список продуктов
GET /v1/products
То же касается других ресурсов, таких как клиенты (Customers). Как разработчик, вы хотите, чтобы ваш API был максимально предсказуемым, позволяя пользователям угадывать, какая комбинация HTTP-команд и конечных точек сработает, основываясь на предыдущем опыте работы. Будьте строго последовательны: новые маршруты должны работать во многом так же, как и существующие. Это не только позволит пользователям быстрее освоить API, но и даст ощущение хорошо продуманного, интуитивно понятного интерфейса.
2. Будьте интуитивно понятны
Предположим, у нас есть объект ресурса Customer, который принимает 3 поля: имя, email и адрес. Сначала мы создаём клиента:
// Запрос
POST /v1/customers
{ "name": "John Watson",
"email": "[email protected]",
"address": "221B Baker Street" }
// Ответ
{
"id": "cus_123",
"object": "customer",
"name": "John Watson",
"email": "[email protected]",
"address": "221B Baker Street"
}
Затем мы решили обновить клиента:
// Запрос
POST /v1/customers/cus_123
{ "address": "London SW1A 1AA" }
// Ответ
{
"id": "cus_123",
"object": "customer",
"name": undefined,
"email": undefined,
"address": "London SW1A 1AA"
}
В этом запросе мы просто обновляем существующий адреса клиента. Но куда делись значения для имени и email? API сделал именно то, что ему было сказано. Он обновил значение адреса, но, поскольку значения имени и email отсутствовали в запросе на обновление, он интерпретировал их отсутствие как запрос на обнуление. Формально это правильно, но является чётким показателем того, что этот API не был разработан для людей. Вместо того, чтобы проверять, был ли передан параметр, разработчики этого API обновляют объект значением атрибута, независимо от того, был он предоставлен или нет.
API преуспевают благодаря своей интуитивности. Операции, подобные описанным выше, должны «просто работать» на основе общего предположения, а не на склонности компьютера делать именно так, как ему было сказано.
Источник: https://dev.to/stripe/designing-apis-for-humans-design-patterns-5847
