REST-API design - allow custom IDs

Question

we are designing an API which can be used by marketplaces and onlineshops to create payments for their customers. To reduce the work the marketplaces and shops have to do to implement our API, we want to give them the ability to use their own user- and contract-IDs rather than storing the IDs we create. It makes it easier for them as they dont have to change/extend their databases. Internally in our database we will still use our own technical IDs. So far we do not run any checks on the custom-IDs (ie uniqueness).

My question is, if it is a good idea in general to let the stores & marketplaces use their own IDs, or if it is bad practice. And if our approach makes sense, should we run checks on the IDs we receive by the stores & marketplaces (ie uniqueness of a user-ID related to the store)?

Example payload for creating a new user via POST /users/ :

{
   customUserId: "fancyshopuserid12345",
   name: "John",
   surName: "Doe"
}

Now the shop can run a GET-request /users/fancyshopuserid12345 to retrieve the new user via our API.

EDIT: We go with both approaches now. If he wants to use his own id he does it like in the example above, if he sets false as the value for customUserId we set our internal ID as value.

Answer 1

Personally i think that it's awesome feature! And i don't see any problems here.
I also think that you don't have validate customers ids, just check that it don't have injection to your persistence layer and it'll be enough.
More over your don't violate any REST conventions - that's why i think it's nice idea...

Answer 2

Well, a cool (RESTful) approach would be to receive URIs instead of custom IDs. That would unfortunately mean that those partner systems would have to publish their own resources in order be able to link to them. This would also solve the unique-ness problem, since you would only have to check whether the URI exists.

If some shop systems are in fact build RESTfully, they may want to actually store a URI instead of id, to be able to navigate seamlessly through their own and your systems. They would only have to add your media-type s to their clients, and that's it.

Other than that, sure you can store IDs of third-party systems. I know of a few trading systems that do exactly that, storing all sorts of third-party IDs, of backend systems, of transport layer ids, etc. It is at least not unheard of.