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 ?
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.
User | Count |
---|---|
7 | |
2 | |
2 | |
2 | |
1 |