POST, GET и другие ?!

К написанию статьи, меня подтолкнуло руководство.

Все началось с того, что надо сделать API для работы WEB приложения, но с нюансом, что оно должно быть написано на JAVA, не путать с JAVASCRIPT.

После недели работы над этой задачей и параллельным изучением JAVA, показал им результат сделанного API. После просмотра SWAGGER , получил массу "негативных отзывов" на названия, типы запросов и т.д. И я решил разобрать, причину данной ситуации.

Типы запросов:

И так начнем с того, что в методах API не было методов PUT, DELETE и т.д. Хотя в JAVA принято, что получение идет через GET, отправка данных через POST, удаление через DELETE, а вставка через PUT.

Но в HTML нет ничего кроме POST и GET! Удивлены шеф? Курим: htmlbook.ru/html/form/method

Естественно, что я переделал методы на ФЭНШУЙ. И сейчас они будут работать, именно так, как этого хочет руководство. А для создания запросов нужного типа, будут использоваться средства javascript. Но как вы понимаете, исчезает обратная совместимость с простыми формами, но для приложения написанного на REACT, это нормально.

Именование методов:

Для работы с АПИ я использовал названия вида:

• /staffers/add - добавление
• /staffers - получение списка
• /staffers/{id} - получение одного

Руководству не понравилось, и в итоге названия стали такие:

• [GET] /xxx/v1/employees
• [GET] /xxx/v1/employees/{id}
• [POST] /xxx/v1/employees/
• [PUT] /xxx/v1/employees/
  
• [DELETE] /xxx/v1/employees/{id}
  

В чем реальное отличие?

1. Добавилась версия API. В разработке сайтом, мы крайне редко используем данное указание, так как в 90% случаев, это АПИ уже НИКОГДА не поменяется. И в моей практике за более чем 10 лет, это работало на те же 90%. А редкие случаи, когда требовалось поменять версию, то просто генерировался новый метод и все.

Но, в крупных и долгих проектах, это хорошая практика. И тут я полностью соглашусь с руководством. Если у вас позволяет время и силы, делайте указание версии и создавайте swagger описание.

2. В PHP, NODE и еще ряде языков, метод добавления и обновления 1. Это позволяет делать подобного рода конструкции:

PHP: $MODEL->FILL($_POST)->SAVE(); 

Вся магия прячется в том, что если в данных придет ID то будет обновление, а если нет, то будет вставка данных.

В JAVA это так не делается, так как при строгой типизации и указании DTO ( Data Transfer Object  а по сути жесткой модели данных) вы не можете использовать произвольные данные (если потанцевать с бубном, то сможете, но это будет не по ФЭНШУЙ). Поэтому данные управляются в том числе на уровне типа запроса.

3. Название staffers редко используемое.. Я задумался откуда у меня была именно такая ассоциация?

Ну ответ простой:

И тут я бы сказал, что надо лучше знать английский и тщательнее проверять подобранные слова. Хотя вопрос этот спорный :)

Подведем итог:

Любое АПИ лучше делать по следующим правилам:

Название начинать с единого элемента, который описывает сущность АПИ (не сущность модели, так как в апи может быть много сущностей), например:

• /maps
• /crm

Далее добавляется версия API:

1. /maps/v1
2. /crm/v1

Далее  к адресу цепляем название сущности, при этом если это список (коллекция) то пишем в множественном числе, если это операция над одним объектом, то в единственном:

1. /maps/v1/houses
2. /maps/v1/token [когда идет не коллекция]

Далее все регулируются методами и параметрами:

• /maps/v1/houses/{id} - получение одного элемента коллекции
• [PUT] /maps/v1/houses/  - обновление записи

Вроде все :)