How to organize REST API?

Question

I'm developing a rest API for our business system. We have the following resources so far:

/sales/orders
/sales/orders/{orderno}
/sales/order-items

There will be lots of resources when the API is finished, so we need to structure it in a good way to make it easy to understand. My question is: should /sales/order-items instead be /sales/orders/order-items? There is maybe no correct answer here, but what would you prefer?

One more question: The sales/order-items resource will list either all open items or all shipped items. It will not be possible to get all order-items regardless of status (open/shipped). The resource URI could the be like this sales/order-items?orderstatus={OPEN/SHIPPED} (the orderstatus query parameter would be mandatory then) or it could be two resources like this sales/order-items/open and sales/order-items/shipped. What is the preferred?

Answer 1

A resource is 'any information that can be named'. Your URIs should be entity based. 'order-items' is not an entity, but a data type.

/sales/order/order-1456321 is the Entity you most likely want. Which would contain the data of all order items.

If you wish to restrict access, you can return a client error if no query string is supplied. and having

/sales/order/order-12345?status=open

etc. Hope this helps.

EDIT:

/sales/order-items or /sales/orders/order-items?

This is domain specific, and really should be answered by a domain expert. Your URI Hierarchy provides scope (and so detail) to your resource. So as an educated guess, It does not make sense to have "order-items" within the scope of "/sales/orders/" because "order-items" is not an "order".

/sales/ordered-items 

seems the most sensible answer.

On a personal note, and not to question your domain too much, Having a strong understanding of the flow of the business and information that's stored may result in something along the lines of these suggestions;

/sales/orders?status=open - Are all orders shipped at once?
/sales/orders/order-1234/packages?status=open - Are orders split into packages?