Rest API Design Query - Multiple Identifiers for Single API Resource Entity

Let's say ,

I have EntityA API Proxy. I need to build following APIs in NorthBound side.

GET EntityA by EntityID

GET EntityA by SomeOtherId

Can we implement something like,

GET /v1/entitya/{entityId}

GET /v1/entitya?some_other_id=xxxx

OR

GET /v1/entitya/{entityId/someOtherId}?identifier_type=entity_id/some_other_id

OR

Note : In below approach, unfortunately southbound service do not have list all entites service that means GET /v1/entitya is actually invalid.

GET /v1/entitya?some_other_id=xxxx

GET /v1/entitya?entity_id=xxxx

Which one do you think is the best approach ? Do you have any other suggestions ?

0 3 11K
3 REPLIES 3

Former Community Member
Not applicable

I think the answer depends on what you want to reveal to the consumer. Do you want the consumer to know there are two IDs for this resource or do you want the consumer to have the appearance of a single ID? If the answer is the later, there is another option:

For ex:

GET /v1/entitya/typea12345

GET /v1/entitya/typeb12345

The first few chars indicate the type code for the ID.

If the consumer is indeed aware of the two type of IDs, then I think it makes sense to do this:

GET /v1/entitya/{entityId}
GET /v1/entitya?some_other_id=xxxx

I have a different opinion thank @Srinandan Sridhar . I think entities ought to have a single unique identifier. I don't think it's helpful to have multiple distinct unique identifiers that refer back to the same entity. I think if you are managing multiple unique identifiers, you're doing something a little off.

It may be that you'd like to retrieve the entity via a search other than the ID. That's easy - no problem. Search by other properties on the entity. And that search may return 0, 1, or more entities. But the search itself does not specify the identifier (Except in the degenerate case).

So

GET /v1/entitya/typea12345

GET /v1/search?q=type%3Dentitya%20and%20flavor%3Dcherry

-or-

GET /v1/search?type=entitya&flavor=cherry

@Dino , Unfortunately, Southbound service can be retrieved using multiple identifiers. And also, Southbound service do not have GET /v1/entitya service.

I like below approach,

GET /v1/entitya?identifiertype=id&entity_id=12321
GET /v1/entitya?identifiertype=some_other_id&some_other_id=1231321

But , when it comes to documentation , it's hard to document above approach . Since, identifiertype is mandatory & entity_id is mandatory only if identifiertype is id. As you rightly said, it should be one single identifier at the end of the day. But southbound service architecture is making this design tricky on NorthBound side.