Немного о том как организовывать API веб-службы

[@gricom]

А нельзя ли немного конкретики? Например опубликуйте часть API, расскажите почему он именно такой.

И объясните пожалуйста, почему у вас операция заказа билета идет через POST, а не через PUT, ведь если через API передается запрос на заказ какого-то конкретного билета (с указанием ряда, места), то получается, что это идемпотентная операция (т.е. состояние системы не зависит от того, сколько раз была выполнена операция), и её следует проводить через PUT.

[@mpetrunin]

Ну конкретно, приводить примеры API — это уже более частная задача. Я же ставил целью объяснить выбор конкретной идеологии\технологии в рамках широко спектра существующих вариантов.

С билетами в театр немного синтетический пример, но поясню. Перед покупкой билета надо убедиться, что место свободно. Если оно свободно, то создается заказ в статусе «неоплачено», который, если его недозаполнить и не оплатить, удалится, скажем, через 10 минут. Кроме того, есть театры, куда билеты продаются без мест. Туда надо проверять вообще наличие свободных мест.

Таким образом, операция предварительного заказа билета на театр без места по сути — создание объекта «заказ» в системе в статусе «неоплачено». Т.е. если я дважды сделаю этот запрос, то дважды будет создан «заказ». Т.е. операция не является идемпотентной, поэтому POST.

А вот для перевода заказа в статус «оплачен» я буду использовать PUT.

[@muromec]

>С билетами в театр немного синтетический пример

так а зачем нам синтетические? мяса нам, мяса!

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

[@mpetrunin]

Попробую в след. топике на тему :)

[@dmitriko]

POST к родительскому ресурсу создает новый ресурс.
PUT только для уже существующих.
Не помню где прочитал, но работает хорошо ;)

[@gricom]

Нет, это не может являться критерием выбора типа запроса. PUT обязан быть идемпотентным!

Например, если вы будете делать инкремент счетчика просмотров существующего ресурса через PUT, то фактически каждый запрос будет изменять состояние этого ресурса, что не подразумевается семантикой PUT-запросов.

[@pred8or]

Проектировщикам REST API весьма рекомендую скачать и прочитать книгу InfoQ Explores: REST. Отличное описание best practices, anti-patterns и немного дискуссий на тему.

Может, кому-то захочется по этой книге сделать статью или несколько на Хабре.

[@mpetrunin]

Спасибо, скачал — почитаю

[@pred8or]

Одной аутентификации недостаточно. Необходимо подписывать сообщения. Неплохая дискуссия на эту тему есть на O'Reilly: Principles for Standardized REST Authentication.

[@mpetrunin]

Спасибо за наводку.

А на какой случай необходима подпись параметров? На случай увода авторизационного ключа?

[@pred8or]

Конечно. Возможностей утечки ключа — масса, особенно если он генерируется только один раз.

[@pred8or]

Ну и, как водится, на случай компрометации ключей необходимо предусматривать инфраструктуру их отзыва, деактивации и т.п. Но для маленьких проектов это, наверное, не слишком актуально.

[@Bonch]

Это как раз решает OAuth2 с его refresh_token.

[@bendingunit22]

Имеет ли смысл подписывать сообщения, если не предполагается, что API будет предоставляться пользователями третьим лицам? В этом случае отдельного аккаунта для робота и базовой авторизации по ssl будет достаточно. По крайней мере, так кажется на первый взгляд.

[@skitalets]

Спасибо, хорошее руководство по организации api для начинающих.

Я, когда делал api для чата, написал все с нуля, без использования сторонних библиотек и протоколов. И считаю, что это был ценный опыт.

[@QuintaDB]

Спасибо! Нам очень помогла ваша статья для разработки нашего API. Кому интересно — mytaskhelper.ru/api/index

[@qweewq]

нельзя ли поподробнее про «пару строчек, и всё готово»? третий день мучаюсь

[@mpetrunin]

Что именно у вас не получается?

[@qweewq]

спасибо, уже разобрался