-1

We are implementing an API and we want to follow best practices for naming the endpoints. However, during the design, we have found a challenge. We have some objects where the key to the objects is a combination of three keys: key1, key2, key3.

We have been following for other objects (e.g. orders) the pattern:

 api/orders?fiter1=value1&filter2=value2  # To retrieve the list of orders that futfill al the filters.  
 api/orders/{key}   # To retrieve an spepcific order

But, what happens if the key is actually a combined key in the database, for example, the combination of day and name of the person for example?

Some developers follow this approach:

1/

 api/order?day=2017-05-20&name=Bob  # This approach I don't like it because the endpoints are singular. 

2/

 api/orders/{month}/{name}  # Don't like it because is really nasty

I have seen a different approach, that I like:

 api/orders/{date:name} 

In this idea, the key is created as a combination of both properties. Is this a good approach?

  • Maybe it's just me, but I have reread your question three times, and I still don't understand it. If you're loading orders for a specific customer for a specific day, just do api/orders?day=2017-05-20&customer=Bob since you seem to dislike (and you're right) the singular form. But it's so obvious that I suppose that there is something else in your question, but what?... – Arseni Mourzenko Jun 22 at 17:13
  • Thanks for your reply, the problem with this approach that you are saying api/orders?day=2017-05-20&customer=Bob is that you will always retrieve one object wrapper into a list, when I just one to retrieve one single object. – ypriverol Jun 22 at 17:29
  • 1
    What if there are multiple orders for the same person in a given day? Anyway, if in a given domain, it is natural that there would always be one and one only order, than what's wrong with your first suggestion, “api/order?day=2017-05-20&name=Bob”? – Arseni Mourzenko Jun 22 at 17:51
  • This is only an example, the main point is that I have a composite id and I don't know the best way to design an endpoint to retrieve only one object without needs to wrapper it into a list. – ypriverol Jun 22 at 18:40
  • I still don't understand your question. Well, let's wait, maybe somebody here understands it and will give you an answer. – Arseni Mourzenko Jun 22 at 19:38
2

REST doesn't constrain your resource identifiers, beyond the expectation that they will satisfy the production rules described in RFC 3986. The machines just don't care. So any spelling that will satisfy your local code review is fine.

Some spellings are more convenient than others, because they encode information that can easily be described by a URI template.

Using paths (api/orders/{month}/{name}) can be convenient when the identifier hierarchy maps well to your resource hierarchy, and you want to use dot segments to describe identifiers.

api/orders/{month}/{name} + xx -> api/orders/{month}

Using query parameters can be convenient on the web, because HTML production rules allow us to use a form as a sort of poor man's URI template. Web browsers (and other HTML capable tools) already know how to build URI like api/order?day=2017-05-20&name=Bob.

api/orders/{date}:{name} 

That's also perfectly fine (assuming you properly escape any reserved characters that happen to occur in {date} or {name}. Note that, from the perspective of a generic consumer, this example uri has three path segments, not four:

api/orders/{date}:{name} + .. -> api/orders

This syntax is also very close to a different idea, called Path Style parameter (sometimes also referred to as Matrix parameters), which uses semi colons to delimit key value pairs

api/orders/{;date,name}

Level 3 compliant template processors should be able to correctly resolve a URI template that includes path style parameters.

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.