Assume a resource URL in the context of REST API:

/sites/<site id or site code>/buildings/<building id or building code>

The value of the two path parameters, <site id or site code> and <building id or building code>, can be either id or code as the name indicates. Implicitly it means:

for instance, there is a building with 1 as building id and rake as building code, and it is located in the site with 5 as the site id and SF as the site code, then the following endpoint URL should retrieve the same result:

  • /sites/5/buildings/1
  • /sites/5/buildings/rake
  • /sites/SF/buildings/1
  • /sites/SF/buildings/rake

In order to reduce the ambiguity, a hint is added into the HTTP header, e.g. path-parameter-type with value as CODE or ID, indicating the type of the given values of the path parameters. As a result, only two types of requests are allowed with the given example:

  • /sites/5/buildings/1 with CODE as path-parameter-type in the http header
  • /sites/SF/buildings/rake with ID as path-parameter-type in the http header

Even though, the implementation of such resource endpoint contains a couple of if conditions due to two different type of path parameters. However, from the end-user's aspect, this seems to be handy.

My question is whether such endpoint design is a good practice or a typical bad practice albeit the fact that there is a type indicator in the HTTP header?

  • Generally speaking a resource should be identified with a single unique identifier. In REST that's what you use to indicate against which resource you want to perform a given action. If it has multiple identifiers then it can be used as a filter, like: /sites?name=SF, /buildings?code=rake. Is this option is viable for you? Commented Jul 7, 2020 at 12:55

2 Answers 2


Yes and no. It depends.

It could be arguable but it depends on the motivations that led the developer to implement it. It could be unnecessary complexity or there could be a legit reason to do it. It might respond to requirements or needs you are not yet aware of or just be motivated by a lack of knowledge or experience designing web APIs. But definitively, we can not state it's bad practice per se.

As @Deduplicator commented, There can be good reasons to have the same content under multiple URLs. One of them can be backward compatibility. Say, initially consumers used CODEand later it was addressed to support ID. Or say, some consumers don't have access to one of the identifiers (CODE or ID).

It could even be unpaid technical debt. Someone changed from CODEto ID but didn't remove the previous implementation. It just added a new capability. Why he/she did so? We don't know.

As for API webs, it's fine identifying the building as

  • /sites/5/buildings/1
  • /buildings/1?site=1
  • /buildings-in-SF/1
  • /asd3fasdfas-2004qasd-asd23-213123-asd

Supporting 1 or all of them is not a design concern. It's a strategic concern. It depends on if you want to provide the API with different ways to access the same information. Or to the same information but in different representations. For example, to make accessible your resources to different consumers with different constraints. This allows you to define different representations depending on the entry point.

If that's good or bad in your case, we can not say.


Are you faced with this API and looking for a way to make it unambiguous? Or are you also designing the API itself?

Assuming, the latter, generally in REST each URI identifies a unique resource. That's what consumers of the API would expect. With your design, 2 different URIs refer to the same resource which I would say is a bad or at least confusing design.

I might be missing a trick but I'm not sure who gains from this approach in any case. There is no benefit to the consumer of the API to have 2 URIs to choose from and it just makes the implementation on the server side more complex.

  • I totally agree with you. This question is asked exactly due to my skepticism on such design. This design is not from me but the existing code base in my current project
    – Rui
    Commented Jun 28, 2020 at 11:43
  • I see, in that case I guess the short answer is: yes it is a bad design :) Commented Jun 28, 2020 at 11:51
  • 3
    There is a reason <link rel="canonical" href="..."> was introduced for http: There can be good reasons to have the same content under multiple URLs. Commented Jun 29, 2020 at 6:52
  • Agreed with Deduplicator. There's nothing wrong on having different ways to identify a resource. The problem is when 1 ID, identifies different resources.
    – Laiv
    Commented Nov 26, 2020 at 9:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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