Построение простого RESTful api

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

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

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

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

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

  • На веб-сайте пользователи регистрируются с помощью электронной почты и пароля. Должен ли я позволить им получить "токен" на странице своего профиля, чтобы пройти с каждым запросом api? (сделает автономный ресурс автономной работы /auth URI избыточным).

  • Рекомендации по структурированию ответа xml? Кажется, что с помощью REST вы должны вернуть либо 200 ok, либо XML или фактические соответствующие коды состояния, то есть 401 и т.д.

Любые общие указатели оценили.

Ответы

Ответ 1

1- для auth, вы можете рассмотреть что-то вроде http-basic или digest auth (примечание - базовое, в частности, небезопасно, если не выше https)

для схемы URL:

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

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

Ответ 2

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

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

Authorization : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Authorization : MyCustomAuthentication foo:bar:n293f82jn398n9r

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

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

Ответ 3

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

Итак, GET для получения информации. POST (или, возможно, PUT) для создания/изменения ресурсов. УДАЛИТЬ для удачного удаления. И HEAD, чтобы проверить метаданные.

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