как должны выглядеть мои URL для этого простого веб-сервиса REST? - PullRequest
Новая
       7

как должны выглядеть мои URL для этого простого веб-сервиса REST?

1 голос
/ 06 марта 2012

Я новичок в REST, но я создал простой веб-сервис, и мне трудно найти простое объяснение того, какой формат URL будет правильным.

Сервис позволяет создать счет-фактуру и провести его через ряд простых этапов утверждения.

(1) Прочитать все счета в формате XML: 

GET: http://localhost/webapp/ws/invoices

(2) Считать один счет в формате XML (например, идентификатор счета = 555): 

GET: http://localhost/webapp/ws/invoices/555

(3) Отправить новый счет: 

POST: http://localhost/webapp/ws/invoices

С атрибутами счета-фактуры ("идентификатор пользователя", "общая цена" и т. Д.), Таких как параметры POST простой формы HTML.

(4) Утвердить счет: 

POST: http://localhost/webapp/ws/invoices/action

С помощью атрибутов действия (например, "userid = 123", invoiceid = 567, "action = APPROVE" или "REJECT" и т. Д.), Таких как параметры POST простой формы HTML.

Работает нормально, но близко ли это к тому, как должен выглядеть веб-сервис RESTful?

Любой совет с благодарностью, спасибо.

Rob

Ответы [ 2 ]

3 голосов
/ 06 марта 2012

URL не делают API RESTful или нет. Более важно четко представлять ваши ресурсы и переходы между ними (через ссылки и формы) и избегать внеполосной информации, которая связывает клиентов с вашей реализацией. RESTful Hypermedia API в трех простых шагах охватывает эту концепцию прекрасно.

1) Создайте корневой ресурс, который обеспечивает хорошо известную отправную точку для всех клиентов и позволяет им обнаруживать доступные службы (это может быть тот же URL-адрес, который используется браузерами. Используйте заголовок Accept, чтобы определить, является ли HTML или ваш Медиа-тип API должен быть возвращен).

GET: http://localhost/webapp

<webapp href="/webapp">
    <invoices href="/webapp/invoices"/>
    ... any other services ...
</webapp>

2) Создайте ресурс коллекции для ваших счетов

GET: http://localhost/webapp/invoices

<invoices href="/webapp/invoices">
    <invoice href="/webapp/invoices/555"/>
    <invoice href="/webapp/invoices/554"/>
    <invoice href="/webapp/invoices/553"/>
    <invoice href="/webapp/invoices/552"/>
    ...
    <search href="/webapp/invoices/" method="get">
        <query type="xpath" cardinality="required"/>
    </search>
    <next href="/webapp/invoices?page=2" method="get"/>
    <create-draft href="/webapp/invoices" method="post">
        <total-price type="decimal" cardinality="optional"/>
        ... user should be picked up automatically based on the authorised user posting the form ...
        ... add other optional and required parameters here. ...
    </create-draft>
</invoices>

Это коллекция, разбитая на страницы, с элементом next, сообщающим клиенту, как получить следующую страницу. Если было недостаточно счетов (например, 5 счетов и каждая страница может содержать 10), тогда элемент next не будет отображаться. Точно так же, если запрашивающая сторона не авторизована для создания счетов, то форма create-draft не будет включена.

Получение следующей страницы будет выглядеть примерно так:

GET: http://localhost/webapp/invoices?page=2

<invoices href="/webapp/invoices">
    <invoice href="/webapp/invoices/545"/>
    <invoice href="/webapp/invoices/544"/>
    <invoice href="/webapp/invoices/543"/>
    <invoice href="/webapp/invoices/542"/>
    ...
    <search href="/webapp/invoices/" method="get">
        <query type="xpath" cardinality="required"/>
    </search>
    <next href="/webapp/invoices?page=3" method="get"/>
    <prev href="/webapp/invoices" method="get"/>
    <create-draft href="/webapp/invoices" method="post">
        <total-price type="xs:decimal" cardinality="optional"/>
        ... user should be picked up automatically based on the authorised user posting the form ...
        ... add other optional and required parameters here. ...
    </create-draft>
</invoices>

3) Создать ресурс для ваших счетов

GET: http://localhost/webapp/invoices/555

<invoice href="/webapp/invoice/555">
    ... details go here ...
    <reject href="/webapp/invoices/555" method="delete">
        <reason type="xs:string" cardinality="required"/>
    </reject>
    <approve href="/webapp/invoices/555" method="put">
       ... add approval parameters here ...
    </approve>
</invoices>

Аналогичным образом, если пользователь не авторизован для отклонения или утверждения счетов-фактур, эти элементы не должны отображаться. То же самое происходит, если счет уже был утвержден (в этом случае, возможно, существует форма отмены).

1 голос
/ 06 марта 2012

ИМХО для процесса утверждения я бы сделал:

(4) Утвердить счет-фактуру: 

PUT: http://localhost/webapp/ws/invoices/555

Поскольку вы собираетесь изменить существующий ресурс, идентифицируемый идентификатором (555), поэтому вам нужно только передать атрибуты, которые будут меняться.

...