Умный учится на своих ошибках, а мудрый — на чужих: как плохое #API партнеров помогает мне проектировать наши интеграции правильно. 🌐
Так получается, что на текущем проекте частенько приходится подключаться к партнерским да и просто публичным API, и вот, что я думаю, анализируя некоторые API: принципы REST не просто так придуманы. Нет, я, конечно, за гибкость и адаптивность, а не за слепое следование правилам, но полное игнорирование best practice приводит к костылям и велосипедам🩼🚴♂️ (экспоненциально разрастающемуся хаосу).
Я не спорю, разработка ПО — процесс нелинейный, но иногда стоит пожертвовать скоростью поставки новой фичи в угоду проработанной архитектуре.
Итак, что довелось повидать (названия эндпоинтов вымышлены, но суть передают):
🚩Эндпоинты-загадки: GET /get_data, POST /process_records. Что за data? Какие records? Пути ничего не говорили о ресурсе. (Это я уж молчу про то, что в названии эндпоинта не принято указывать действие, оно и так обозначено в методе, в данном случае get).
🚩Игнор всех методов, кроме POST: Всё через POST, даже для простейшего получения данных. POST /getUserOrders вместо логичного GET /users/{id}/orders. Да, бывают кейсы, когда использование POST для получения данных можно обосновать. Например, получить данные по сотне-другой заявок, которые так удобно передать через Body, чего не сделаешь в GET. Я все равно при проектировании стараюсь использовать именно GET для получения, а список каких-нибудь id пробую передавать через query (благо нынче можно позволить вызывать очень длинные HTTP-запросы). Тем не менее, для таких исключительных кейсов это вопрос дискуссионный, но не всегда же! 🙈
🚩Коды ошибок, как отдельный вид извращений искусства: В ответе приходил статус 200 OK, а в теле:
Что за код 47? Это надо было угадать или искать в недоступной документации. Ну или что-то, как на картинке в посте. 🤡
Какие для себя на основе этого я делаю выводы, чтобы не допускать такого? Удивительно, но, видимо, стоит просто следовать принципам REST, которые всем уже оскомину набили.
💚Ресурсы, а не операции. Путь — это существительное, которое отвечает на вопрос «Что?».
Плохо: POST /calculateTotal
Хорошо: GET /cart/{id}/total
💚HTTP-методы — это наши глаголы. Используем их по назначению, это снимает 50% вопросов.
GET /orders (получить)
POST /orders (создать)
PUT /orders/{id} (заменить)
PATCH /orders/{id} (частично обновить)
💚Честные статусы. Если ресурс не найден — это 404, а не 200 с текстовой ошибкой. Если ошибка в данных клиента — 400 с понятным описанием в теле.
По традиции философский вывод в конце: Качество API — это не техническая прихоть, а вопрос бизнес-эффективности, ведь как и потраченные клиентами дни на анализ и подключение к некачественному API, так и человеко-часы, затрачиваемые владельцами на сопровождение и развитие такого бардака — это прямые финансовые потери.
#REST #API #HTTP #интеграция
Так получается, что на текущем проекте частенько приходится подключаться к партнерским да и просто публичным API, и вот, что я думаю, анализируя некоторые API: принципы REST не просто так придуманы. Нет, я, конечно, за гибкость и адаптивность, а не за слепое следование правилам, но полное игнорирование best practice приводит к костылям и велосипедам🩼🚴♂️ (экспоненциально разрастающемуся хаосу).
Я не спорю, разработка ПО — процесс нелинейный, но иногда стоит пожертвовать скоростью поставки новой фичи в угоду проработанной архитектуре.
Итак, что довелось повидать (названия эндпоинтов вымышлены, но суть передают):
🚩Эндпоинты-загадки: GET /get_data, POST /process_records. Что за data? Какие records? Пути ничего не говорили о ресурсе. (Это я уж молчу про то, что в названии эндпоинта не принято указывать действие, оно и так обозначено в методе, в данном случае get).
🚩Игнор всех методов, кроме POST: Всё через POST, даже для простейшего получения данных. POST /getUserOrders вместо логичного GET /users/{id}/orders. Да, бывают кейсы, когда использование POST для получения данных можно обосновать. Например, получить данные по сотне-другой заявок, которые так удобно передать через Body, чего не сделаешь в GET. Я все равно при проектировании стараюсь использовать именно GET для получения, а список каких-нибудь id пробую передавать через query (благо нынче можно позволить вызывать очень длинные HTTP-запросы). Тем не менее, для таких исключительных кейсов это вопрос дискуссионный, но не всегда же! 🙈
🚩Коды ошибок, как отдельный вид извращений искусства: В ответе приходил статус 200 OK, а в теле:
{ "status": "error", "code": 47 }
Что за код 47? Это надо было угадать или искать в недоступной документации. Ну или что-то, как на картинке в посте. 🤡
Какие для себя на основе этого я делаю выводы, чтобы не допускать такого? Удивительно, но, видимо, стоит просто следовать принципам REST, которые всем уже оскомину набили.
💚Ресурсы, а не операции. Путь — это существительное, которое отвечает на вопрос «Что?».
Плохо: POST /calculateTotal
Хорошо: GET /cart/{id}/total
💚HTTP-методы — это наши глаголы. Используем их по назначению, это снимает 50% вопросов.
GET /orders (получить)
POST /orders (создать)
PUT /orders/{id} (заменить)
PATCH /orders/{id} (частично обновить)
💚Честные статусы. Если ресурс не найден — это 404, а не 200 с текстовой ошибкой. Если ошибка в данных клиента — 400 с понятным описанием в теле.
По традиции философский вывод в конце: Качество API — это не техническая прихоть, а вопрос бизнес-эффективности, ведь как и потраченные клиентами дни на анализ и подключение к некачественному API, так и человеко-часы, затрачиваемые владельцами на сопровождение и развитие такого бардака — это прямые финансовые потери.
#REST #API #HTTP #интеграция