Ресурсы API REST API, данные для возврата?

Question

Если мы имеем customers и orders, я ищу правильный RESTful способ получить эти данные:

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
    } 
} 

1. GET /customers/123/orders
2. GET /customers/123?inc-orders=1

Я правильно, что в последней части/папка URL-адреса, за исключением параметров строки запроса, должен быть возвращен ресурс ..?

Если это так, номер 1 должен только возвращать данные заказа и не включать данные клиента. Пока номер 2 указывает непосредственно на клиента 123 и использует параметры строки запроса для обработки/фильтрации возвращаемых данных клиента, в данном случае включая данные заказа.

Какой из этих двух вызовов является правильным вызовом RESTful для вышеупомянутого JSON ..? ... или есть секретный номер 3 вариант ..?

Answer 1

У вас есть 3 варианта, которые я думаю, можно было бы считать успокоительных.

1) GET /customers/12 Но всегда включайте заказы. У вас есть ситуация, когда клиент не хочет использовать заказы? Или массив заказов может стать очень большим? Если это так, вам может понадобиться другой вариант.

2) GET /customers/123, который может включать в себя ссылку на свои заказы, как так:

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": { 
     "href": "<link to you orders go here>" 
    } 
    } 
} 

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

3) GET /customers/123?fields=orders Это похоже на ваш второй подход. Это позволит клиентам использовать ваш API более эффективно, но я бы не пошел по этому маршруту, если вам действительно не нужно ограничивать поля, возвращаемые с вашего сервера. В противном случае это добавит излишнюю сложность в ваш API, который вам нужно будет поддерживать.

Answer 2

JSON, что вы вывесили, как выглядит то, что будет результатом

GET /customers/123 

при условии, что ресурс клиента содержит коллекцию орденов, как собственность; альтернативно вы можете вставлять их или предоставлять ссылку на них.

Последнее приведет к чему-то вроде этого:

GET /customers/123/orders 

, который будет возвращать что-то вроде

{ 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, 
     { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
} 

Answer 3

Я ищу правильный RESTful способ получить эти данные

Просто выполнить запрос HTTP GET на URI, который указывает на ресурс, который производит эти данные!

TL; DR

• REST не заботится о URI дизайна - но на своих ограничений!
• Клиенты выполняют переходы состояний посредством возможных действий, возвращаемых сервером посредством динамически идентифицированных гиперссылок, содержащихся в ответе.
• Клиенты и сервера могут договориться о предпочтительном типе гипермедиа
• Вместо вложения всего (суб) ресурса рассмотреть только возвращая ссылку на этот ресурс так клиент может посмотреть его, если заинтересованные

---

Во-первых, REST действительно не заботится о дизайне URI, пока URI уникален. Конечно, простой дизайн URI легче понять для людей, хотя по сравнению с HTML фактическая ссылка может быть скрыта за более выраженным текстом и, следовательно, также не так важна для людей, пока они могут найти ссылку и может выполнить против него действие. Далее, почему вы думаете, что ваш «ответ» или API RESTful? Чтобы вызвать API RESTful, API должен уважать пару constraints. Среди этих ограничений есть одно довольно известное модное слово: гипертекст как движок состояния приложения (HATEOAS).

REST - это обобщенная концепция Сети, которую мы используем каждый день. Обычная задача для веб-сессии заключается в том, что клиент запрашивает что-то, где сервер отправляет HTML-документ с большим количеством ссылок и других ресурсов, которые клиент может использовать для запроса дальнейших страниц или для потоковой передачи видео (или того, что когда-либо). Операция пользователя g на клиенте может использовать возвращаемую информацию для продолжения, запрашивать новые страницы, отправлять информацию на сервер и т. Д. И т. Д. То же самое относится и к приложениям RESTful. Это был REST, просто определяемый как HATEOAS. Если теперь вы посмотрите на свой «ответ» и дважды проверьте с помощью ограничения HATEOAS, вы можете увидеть, что ваш ответ не содержит ссылок для начала. Поэтому клиенту необходимо знание домена, чтобы продолжить.

JSON сам по себе не самый лучший тип IMM гипермедиа, поскольку он определяет только общий синтаксис данных, но не несет никакой семантики, подобно простому XML, который может иметь некоторые DTD или схемы, которые клиент может использовать для проверки документ и проверить, имеются ли дополнительные семантические правила в другом месте. Есть несколько типов гипермедиа, которые накапливаются на JSON, которые, вероятно, лучше подходят, например, f.e. application/hal+json (Хорошее сравнение типов гипермедиа на основе JSON можно найти в этом blog post). Вы, конечно, имеете право определять свой собственный тип гипермедиа, хотя некоторые клиенты могут не понимать его из коробки.

Если вы принимаете f.e. посмотрите на HAL, вы увидите, что он определяет элемент _embedded, где вы можете поместить определенные ресурсы. Это кажется идеальным в вашем случае. В зависимости от вашего дизайна, orders также может быть ресурсом самостоятельно и, таким образом, быть доступен через GET /orders/{orderId}. Вместо того, чтобы встраивать весь под-ресурс, вы также можете просто включить ссылку на этот (дополнительный) ресурс, чтобы клиент мог искать данные, если они заинтересованы.

Если есть случаи, когда вы хотите вернуть только данные клиента и другие случаи, когда вы хотите также включить другие данные, вы можете f.e. определить разные типы гипермедиа (на основе HAL f.e.) для обоих, один возвращает только данные клиента, а другой также включает другие данные. Эти типы могут быть названы так: application/vnd.yourcompanyname.version.customers.hal+json или application/vnd.yourcompanyname.version.customer_orders.hal+json. Хотя это, безусловно, накладные расходы на разработку по сравнению с добавлением простого запроса к запросу, семантика более понятна, а служебные данные документации относятся к типу гипермедиа (или представлению), а не к операции HTTP.

Вы можете, конечно, также определить некоторую структуру вида, в которой один вид возвращает данные клиента только в том случае, когда другое представление возвращает данные клиента, включая заказы, похожие на response, которые я дал по не столь несвязанной теме.

Answer 4

Ресурс (идентифицируется по URL полный) такой же, клиент. Только Представление отличается, с или без встроенных заказов.

Используйте Контент для переговоров, чтобы получить разные представления для одного и того же ресурса.

Запрос

GET GET /customers/123/ 
Accept: application/vnd.acme.customer.short+json 

Response

200 OK 
Content-Type: application/vnd.acm.customer.short+json 

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    } 
} 

Запрос

GET GET /customers/123/ 
Accept: application/vnd.acme.customer.full+json 

отклика

200 OK 
Content-Type: application/vnd.acme.customer.full+json 

{ 
    "customer": { 
    "id": 123, 
    "name": "Jim Bloggs" 
    "orders": [ 
     { 
     "id": 123, 
     "item": "Union Jack Keyring", 
     "qty": 1 
     }, { 
     "id": 987, 
     "item": "London Eye Ticket", 
     "qty": 5 
     } 
    ] 
    } 
}