Rest API design with multiple unique ids
<p>Currently, we are developing an API for our system and there are some resources that may have different kinds of identifiers.
For example, there is a resource called <code>orders</code>, which may have an unique order number and also have an unique id. At the moment, we only have URLs for the id, which are these URLs:</p>
<pre><code>GET /api/orders/{id}
PUT /api/orders/{id}
DELETE /api/orders/{id}
</code></pre>
<p>But now we need also the possibility to use order numbers, which normally would result into:</p>
<pre><code>GET /api/orders/{orderNumber}
PUT /api/orders/{orderNumber}
DELETE /api/orders/{orderNumber}
</code></pre>
<p>Obviously that won't work, since id and orderNumber are both numbers.</p>
<p>I know that there are some similar questions, but they don't help me out, because the answers don't really fit or their approaches are not really restful or comprehensible (for us and for possible developers using the API). Additionally, the questions and answers are partially older than 7 years.</p>
<p>To name a few:</p>
<p><strong>1. Using a query param</strong></p>
<p>One suggests to use a query param, e.g.</p>
<pre><code>GET /api/orders/?orderNumber={orderNumber}
</code></pre>
<p>I think, there are a lot of problems. First, this is a filter on the orders collections, so that the result should be a list as well. However, there is only one order for the unique order number which is a little bit confusing. Secondly, we use such a filter to search/filter for a subset of orders. Additionally, a query params is some kind of a second-class parameter, but should be first-class in this case. This is even a problem, if I the object does not exist. Normally a get would return a 404 (not found), but a <code>GET /api/orders/?orderNumber=1234</code> would be an empty array, if the order 1234 does not exist.</p>
<p><strong>2. Using a prefix</strong></p>
<p>Some public APIs use some kind of a discriminator to distinguish between different types, e.g. like:</p>
<pre><code>GET /api/orders/id_1234
GET /api/orders/ordernumber_367652
</code></pre>
<p>This works for their approach, because <code>id_1234</code> and <code>ordernumber_367652</code> are their real unique identifiers that are also returned by other resources.  However, that would result in a response object like this:</p>
<pre><code>{
  &quot;id&quot;: &quot;id_1234&quot;,
  &quot;ordernumber&quot;: &quot;ordernumber_367652&quot;
  //...
}
</code></pre>
<p>This is not very clean, because the type (id or order number) is modelled twice. And apart from the problem of changing all identifiers and response objects, this would be confusing, if you e.g. want to search for all order numbers greater than 67363 (thus, there is also a string/number clash). If the response does not add the type as a prefix, a user have to add this for some request, which would also be very confusing (sometime you have to add this and sometimes not...)</p>
<p><strong>3. Using a verb</strong></p>
<p>This is what e.g. Twitter does: their URL ends with <code>show.json</code>, so you can use it like:</p>
<pre><code>GET /api/orders/show.json?id=1234 
GET /api/orders/show.json?number=367652
</code></pre>
<p>I think, this is the most awful solution, since it is not restful. Furthermore, it has some of the problems that I mentioned in the query param approach.</p>
<p><strong>4. Using a subresource</strong></p>
<p>Some people suggest to model this like a subresource, e.g.:</p>
<pre><code>GET /api/orders/1234 
GET /api/orders/id/1234   //optional
GET /api/orders/ordernumber/367652
</code></pre>
<p>I like the readability of this approach, but I think the meaning of <code>/api/orders/ordernumber/367652</code> would be &quot;get (just) the order number 367652&quot; and not the order. Finally, this breaks some best practices like using plurals and only real resources.</p>
<p>So finally, my questions are: Did we missed something? And are there are other approaches, because I think that this is not an unusual problem?</p>