Search code examples
apirestsemanticsendpointidentifier

REST Endpoint with more then one identifier

I have this case where i need to get an item that can be identified by more the one id. And the consumer should be able to decide which one they use.

/product/{productId}
/product/{gtin}
/product/{pzn}

If i do it like displayed above, it is not clear anymore what ID the consumer is using.

My solution so far:

/product/productId/{productId}
/product/gtin/{gtin}
/product/pzn/{pzn}

What is the best practice to deal with this kind of variety?

Solution

  • What is the best practice to deal with this kind of variety?

    Anything that ensures your identifiers aren't ambiguous is fine.

    On the web, what you'll see commonly is the use of key/value pairs in the query string, because that is natively supported by HTML

    /product?productId={productId}
/product?gtin={gtin}
/product?pzn={pzn}

    If you don't care about HTML support, but still want to be able to take advantage of general purpose tooling, then look into URI Templates which allow you to communicate other URI construction recipes.

    /product/productId/{productId}
/product?productId={productId}

    Either of these alternatives are fine. The latter spelling works better with HTML forms, the former spelling works better with relative resolution.

    How to choose? since the machines don't care, prioritize some group of humans impacted by the choice (operators reading logs, writers producing documentation, consumers looking at a browser history), and choose the spelling that best suits their needs.