Веб-службы RESTful: имена методов, входные параметры и возвращаемые значения? - PullRequest
Новая
       4

Веб-службы RESTful: имена методов, входные параметры и возвращаемые значения?

2 голосов
/ 14 февраля 2010

Я пытаюсь разработать простой REST API. Я все еще пытаюсь понять основные архитектурные парадигмы для этого. Мне нужна помощь со следующим:

  1. «Ресурсы» должны быть существительными, верно? Итак, у меня должен быть «пользователь», а не «getUser», верно?

  2. Я видел такой подход в некоторых API: www.domain.com/users/ (список возврата), www.domain.com/users/user (сделать что-то определенное для пользователя). Этот подход хорош?

  3. В большинстве примеров, которые я видел, входные и выходные значения обычно представляют собой просто пары имя / значение (например, color = 'red'). Что если я захочу отправить или вернуть что-то более сложное, чем это? Я вынужден иметь дело только с XML?

  4. Предположим, что PUT для / user / method добавляет нового пользователя в систему. Каков будет хороший формат для входного параметра (предположим, что нужны только поля 'username' и 'password')? Что будет хорошим ответом, если пользователь успешен? Что если пользователь потерпел неудачу (и я хочу вернуть описательное сообщение об ошибке)?

  5. Что такое хороший и простой подход к аутентификации и авторизации? Я хотел бы ограничить большинство методов для пользователей, которые успешно "вошли". Передача имени пользователя / пароля при каждом вызове в порядке? Считается ли передача токена более безопасной (если да, то как это должно осуществляться с точки зрения срока действия и т. Д.)?

Ответы [ 2 ]

9 голосов
/ 14 февраля 2010

Для пункта 1 да. Ожидаются существительные.

Для пункта 2 я бы ожидал, что /users выдаст мне список пользователей. Я ожидаю, что /users/123 даст мне конкретного пользователя.

Для пункта 3 вы можете вернуть все что угодно. Ваш клиент может указать, что он хочет. например text/xml, application/json и т. Д. С помощью заголовка HTTP-запроса, и вы должны как можно больше выполнять этот запрос (хотя вы можете обрабатывать, скажем, text/xml - это было бы разумно во многих ситуациях ).

Для пункта 4 я бы ожидал от POST до создания нового пользователя. PUT будет обновлять существующий объект. Для сообщения об успехе или ошибках вы должны использовать существующие HTTP-коды успеха / ошибок. например 200 OK. См. этот SO-ответ для получения дополнительной информации.

6 голосов
/ 14 февраля 2010

наиболее важным ограничением REST является ограничение гипермедиа («гипертекст как движок состояния приложения»). Представьте, что ваше веб-приложение представляет собой конечный автомат, в котором клиент может запрашивать каждое состояние (например, GET /user/1). Как только клиент имеет одно такое состояние (например, пользователь просматривает веб-страницу), он видит множество ссылки, по которым он может перейти, чтобы перейти к следующему состоянию в приложении. Например, может быть ссылка из «пользовательского состояния», по которой клиент может перейти, чтобы перейти в состояние подробностей.

Таким образом, сервер представляет клиенту конечный автомат приложения по одному состоянию за один раз во время выполнения. Умная вещь: поскольку конечный автомат обнаруживается во время выполнения в состоянии за один раз, сервер может динамически изменять конечный автомат во время выполнения.

Сказав это ...

на 1. ресурсы по существу представляют состояния приложения, которые вы хотите представить клиенту. Часто они будут точно соответствовать объектам домена (например, пользователю), но убедитесь, что вы понимаете, что предоставляемые вами представления являются не просто сериализованными объектами домена, а состояниями вашего веб-приложения.

Мышление с точки зрения GET / users / 123 в порядке. НЕ помещайте никаких действий в URI. Хотя это и не вредно (это просто непрозрачная строка), оно, по меньшей мере, сбивает с толку.

на 2. Как сказал Брайан. Возможно, вы захотите взглянуть на RFC-протокол публикации Atom (5023), поскольку он довольно хорошо объясняет циклы создания / чтения / обновления.

на 3. Фокус на документ ориентированных сообщений. Типы медиа являются неотъемлемой частью REST, потому что они обеспечивают семантику приложения (полностью). не используйте универсальные типы, такие как application / xml или application / json, так как вы объедините своих клиентов и серверы вокруг часто неявной схемы. Если ничего не соответствует вашим потребностям, просто придумайте свой собственный тип.

Может быть, вы заинтересованы в примере, который я взламывал вместе с помощью UBL: http://www.nordsc.com/blog/?cat=13

на 4. Обычно, используйте POST / users / для создания. Посмотрите на RFC 5023 - это прояснит это. Это легко понять спецификации.

на 5. Поскольку вы не можете использовать сеансы (сервер с состоянием) и быть RESTful, вы должны отправлять учетные данные в каждом запросе. Различные схемы аутентификации HTTP уже справляются с этим. Это также важно в отношении кэширования, поскольку заголовок HTTP-авторизации имеет специальную указанную семантику для кэширования (без публичного кэширования). Если вы введете свои учетные данные в файл cookie, вы потеряете этот важный элемент.

Все коды состояния HTTP имеют определенную семантику приложения. Используйте их, не передавайте свою семантику ошибок через HTTP.

Вы можете посетить #rest IRC или присоединиться к rest-обсуждения на Yahoo для подробных обсуждений.

Ян

...