Создание простого УСПОКОИТЕЛЬНОГО API
Я желаю сделать API быстро, после принципов REST - для простого веб-приложения, которое я создал. Первое место API будет использоваться, должно взаимодействовать через интерфейс с приложением для iPhone. API только должен обработать несколько базовых вызовов, но все требуют аутентификации, ничто не общедоступные данные.
- входите в систему/аутентифицируйте в пользователя
- получите список записей в группе пользователей
- получите список снова, только те, которые изменились (недавно добавленный или обновленный)
- запись обновления
Так, следующие принципы REST, я установил бы схему uri?:
- mysite.com/api/auth (СООБЩЕНИЕ?)
- mysite.com/api/users (ДОБИРАЕТСЯ)
- mysite.com/api/update (СООБЩЕНИЕ?)
и ответы будут в XML для начала, JSON слишком позже.
На веб-сайте пользователи входят в систему с электронной почтой и паролем. Я должен позволить им заставить 'маркер' на своей странице профиля передавать с каждым запросом API? (сделал бы одинокий '/auth' ресурсом URI избыточный).
Лучшие практики для структурирования ответа xml? Кажется с REST, что необходимо возвратиться или 200 хорошо и XML или фактические надлежащие коды состояния т.е. 401 и т.д.
Ценятся любые общие указатели.
3 ответа
1- для аутентификации, возможно, вы захотите рассмотреть что-то вроде http-basic или digest auth (обратите внимание - basic, в частности, небезопасен, если не работает через https)
для урлов схема:
- /api/auth не нужна, если вы используете basic или digest.
- /api/group/groupname/, вероятно, более каноничен
- /api/update обычно выполняется как /api/users/username (POST) с добавлением новых данных - ресурсом является пользователь, POST - глагол
- в остальном, в основном, ваш API выглядит нормально, многое зависит от того, являются ли группы иерархическими, и пользователи должны жить в группе - если да, ваши урлы должны отражать это и быть навигационными.
2- коды состояния должны отражать статус - 200 для OK, 401 для отказа в доступе, 404 для не найдено, 500 для обработки ошибки. Как правило, вы должны возвращать XML-запись только в том случае, если у вас хороший запрос
Аутентификация в API всегда работает путем отправки некоторого токена аутентификации в заголовке запроса. То есть, даже при использовании отдельного подхода к входу в систему / auth , вы должны вернуть пользователю некоторый токен, возможно, cookie, который необходимо будет отправлять вместе с каждым запросом.
HTTP уже предоставляет для этой цели специальный заголовок : Авторизация .
Самая простая HTTP-авторизация - это Базовая аутентификация доступа HTTP :
Authorization : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Дайджест-аутентификация - еще одна, более безопасная схема. Вы можете использовать это поле заголовка для любой формы аутентификации, которую захотите, даже для вашей собственной реализованной аутентификации.
Authorization : MyCustomAuthentication foo:bar:n293f82jn398n9r
Вы можете отправить вышеупомянутый токен входа в это поле. Или вы можете использовать схему подписи запроса, в которой определенные поля запроса хешируются вместе с паролем пользователя, в основном отправляя пароль без отправки пароля (аналогично дайджест-аутентификации, но вы можете использовать что-то получше, чем md5 ). Это отменяет отдельный шаг входа в систему. AWS использует этот метод .
Для API в целом хорошо используйте коды состояния HTTP , чтобы указать, что происходит.
В целом вы на правильном пути. Схема URI должна быть основана на идее ресурсов, и вы должны использовать соответствующий метод для выполнения работы.
Итак, GET для получения информации. POST (или, может быть, PUT) для создания/изменения ресурсов. DELETE для удаления. И HEAD для проверки метаданных.
Структура вашего XML не имеет много общего с RESTful API, если предположить, что она не требует управления состоянием. Тем не менее, у вас правильная идея. Если это хороший запрос, верните нужный XML (для GET-запроса) и код состояния 200. Если это плохой запрос, вы также можете, а в некоторых случаях и должны, вернуть что-то еще, кроме кода состояния. В общем, ознакомьтесь со спецификацией HTTP и следуйте ей как можно точнее.