Создание простого RESTful API

Question

Я хочу быстро создать API, следуя принципам REST - для простого веб-приложения, которое я создал. Прежде всего, API-интерфейс будет использоваться для взаимодействия с приложением для iPhone. API-интерфейс должен обрабатывать только несколько базовых вызовов, но все они требуют аутентификации, ничто не является общедоступными данными.

• Войти / аутентифицировать пользователя
• получить список записей в группе пользователей
• снова получить список, только те, которые были изменены (добавлены или обновлены)
• обновить запись

Итак, следуя принципам REST, я бы настроил схему uri?:

• mysite.com / api / auth (POST?)
• mysite.com / api / users (GET)
• mysite.com / api / update (POST?)

и ответы будут в XML для начала, JSON тоже позже.

1. На сайте пользователи авторизуются по электронной почте и паролю. Должен ли я позволить им получать «токен» на странице своего профиля для передачи при каждом запросе API? (сделает автономный ресурс '/ auth' URI избыточным).

2. Лучшие практики для структурирования ответа xml? Похоже, с REST, что вы должны вернуть либо 200 ok и XML или фактические правильные коды состояния, т.е. 401 и т. Д.

Любые общие указатели приветствуются.

Answer 1

1 - для аутентификации вы можете рассмотреть что-то вроде http-basic или дайджест-аутентификации (примечание - в частности, basic небезопасен, если не через https)

для схемы URL:

• / api / auth не требуется, если вы используете basic или digest.
• / api / group / groupname /, вероятно, является более каноническим
• / api / update обычно выполняетсякак / api / users / username (POST) с добавленными новыми данными - ресурс - это пользователь - POST - это глагол
• в противном случае, в основном ваш API выглядит нормально, многое зависит от того, являются ли группы иерархическими, и пользователидолжны жить в группе - если это так, ваши URL должны отражать это и быть пригодными для навигации.

2- коды состояния должны отражать статус - 200 для OK, 401 для отказа в доступе, 404 для не найденного, 500для обработки ошибок.Как правило, вы должны возвращать XML-запись, только если у вас есть хороший запрос

Answer 2

Аутентификация в API всегда работает, посылая некоторый токен аутентификации в заголовок запроса.Т.е. даже при использовании отдельного подхода /auth для входа в систему вы должны вернуть пользователю некоторый токен, возможно, файл cookie, который необходимо будет отправлять вместе с каждым запросом.

HTTP уже предоставляет выделенный заголовок для этой цели: Authorization.
Самым базовым HTTP-авторизацией является HTTP-аутентификация с базовым доступом :

Authorization : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Authorization : MyCustomAuthentication foo:bar:n293f82jn398n9r

В этом поле вы можете отправить вышеупомянутый маркер входа.Или вы можете использовать схему подписания запроса, в которой определенные поля запроса хэшируются вместе с паролем пользователя, в основном отправляя пароль без отправки пароля (аналогично дайджест-аутентификации, но вы можете использовать что-то лучше, чем md5).Это уничтожает отдельный шаг входа в систему. AWS использует этот метод .

Для API в целом, используйте HTTP коды состояния , чтобы указать, что происходит.

Answer 3

Как правило, вы на правильном пути. Схема URI должна основываться на идее ресурсов, и вы должны использовать соответствующий метод для выполнения работы.

Итак, ПОЛУЧИТЕ, чтобы получить информацию. POST (или, возможно, PUT) для создания / изменения ресурсов. УДАЛИТЬ для хорошо, удалить. И ГОЛОВУ, чтобы проверить метаданные.

Структура вашего XML не имеет ничего общего с RESTful API, при условии, что он не требует управления состоянием. Тем не менее, у вас есть правильная идея. Если это хороший запрос, верните желаемый XML (для запроса GET) и код состояния 200. Если это плохой запрос, вы можете, а в некоторых случаях и нужно, вернуть что-то, кроме только кода состояния. В основном, ознакомьтесь со спецификацией HTTP и следуйте ей как можно точнее.