1

I am new to restful services and need some clarification with constructing the URI for a restful service.

Suppose the hierarchy of my data is as follows - products/types/prodids/orders.

Is this URI truly a RESTful URI:

/restws/products/types/abc/prodids/1234/orders

What I am looking to get out of this URI is to list all the orders for all product types of 'abc' with id 1234.

restws is the context root.

Is this a good approach?

  • 1
    There's no such thing as a "RESTful URI". REST treats URIs as opaque, and says nothing about what they should look like. – Eric Stein Aug 21 '18 at 18:48
  • Not really. In theory you can do whatever you want, but when your request starts getting complex like this, it might be worth posting a JSON object to query the information. At least then the intent is clear. I would not be able to infer the meaning of your URL without the explanatory text. – Berin Loritsch Aug 21 '18 at 19:00
3

First thing to note is that the recommended "resource" syntax for REST URIs is a convention which is not always easy to apply to actual use cases. So, while a reasonable guideline, it is just a guideline.

That being said, usually you use URIs with only path elements (i.e. no query string) to identify objects by their IDs. So, assuming your orders have unique IDs, it would be common to access them via URIs of the form /restws/orders/1234. If an order is uniquely identified by an order ID and a product ID because order IDs are unique within a given product but not globally, a URI such as /restws/products/1234/orders/567 would be reasonable.

However, if order IDs are unique globally and you want to just find orders which match certain criteria, such as matching a product ID, type, and perhaps in the future order date, price, and so on, a query string format would be more appropriate: /restws/orders?productId=1234&date=2018-08-21 etc. So your chocie of API actually depends on what the unique IDs ("primary keys") of your orders are and what are just search criteria which may match zero or more orders.

In most cases it is also a good idea to avoid redundancy - for example I would expect product with given ID to be of one specific type, so forcing the user to enter both the ID and the type in the path URL would be a bad API. But if the IDs are unique only within a specific type, then of course the user must pass both in order to identify the resource.

| improve this answer | |
  • Thank you for the detailed explanation. So if I understand this right, query parameters would probably be the better way to do construct this URI - it would be /restws/products?types=abc&prodids=1234. Is that right? – Rest88 Aug 21 '18 at 19:16
  • @Rest88 Yes, I think so. – Michał Kosmulski Aug 22 '18 at 7:24

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.