Приятно делать что-то, что не сосет. Если это не пылесос, конечно (честно скажу, весь пост писал только ради этой шутки). Вот Дерек Комартен тоже так считает и поэтому выпустил видос, как делать несосущие API.
Вот таймкоды советов и краткое описание:
UPD Примечание редакции: каждый совет в видосе снабжается припиской “Это может быть удобно, применяйте осознанно”. Так что не переживайте, если в вашем АПИ чего-то из этого нет, это не значит, что ваше АПИ сосет. Ну или чье-то АПИ сосет.
1️⃣ ID шники должны что-то значить. Ну то есть Idшник не такой 556F673F-3013-423D-8AC7-14BF1E9C316E , а такой CA-ON-556F673F-3013-423D-8AC7-14BF1E9C316E, где CA-ON означает Canada-Ontario, ну и соответственно мы понимаем, что эта сущность как-то связана с этой локацией.
2️⃣ Не душите себя форматом вывода. Типа в ответе не отдавайте JSON массив объектов, а JSON объект с полем в виде массива. Во втором случае будет удобнее изменять ответ, если что-то понадобистся добавить в корень. Кстати, недавно у меня ровно такой случай был. Так что совет прям актуальный.
⭐ 3️⃣и 4️⃣ совет. Возвращать набор действий, которые вы можете совершить с объектом и ссылки на них. То есть если у вас в ответе на запрос GetOrder пришел заказ в статусе “ожидает”, то отправьте список запросов, которые можно сделать по этому заказу. И так же отправьте ссылки на эти запросы.
5️⃣ Используйте доменные определения вместо технических. Ну то есть CancelOrder это не UpdateOrder с параметром Cancel, а это прям CancelOrder. Да, что-то будет CRUDом, но не все.
Для меня самым интересным с одной стороны и самым спорным стали 3 и 4 совет. Действительно круто, когда ты прям присылаешь клиенту, что можно сделать с объектом прямо сейчас, избавляя его от необходимости самому догадываться об этом:
{
orderId: CA-ON-556F673F,
status: Pending,
actions: [
{
name: "CancelOrder",
uri: "https://mylittleoregano.org/order/CA-ON-556F673F/cancel",
method: "PUT"
}
]
}Почему это удобно? Если вдруг имя метода поменяется или формат параметров, то не придется версионировать АПИ и просить клиентов перейти на новую версию.
С другой стороны, я не вполне понимаю, как это защитит от ситуации, если, к примеру, заказ перестает быть возможным отменить в статусе Pending? Ну типа логику на клиенте все равно придется переписывать. Хотя это и станет удобнее, разумеется.
🅰️ Итого: Вы можете отправлять с бэка набора действий, которые можно совершить с объектом. Это может помочь вам избавиться от необходимости версионирования АПИ, так как вы сами контролируете формат ссылок. Также этим вы избавите клиентов от необходимости помнить, что можно и когда, так как вы будете присылать только те действия, которые можно совершить.
Если кто-то юзал такое, или юзает, вот было бы интересно узнать опыт использования и всякие подводные камни.