1

In my application, a client can create resources for which we compute our ID and assign it to the resource.

However a client can also reference, for every resource, a specific ID it wants to use (we call it external ID) so that we do not force the client to only use our IDs.

We then have the following endpoints:

  • POST /resources/ to create a resource with an optional external_id in the payload
  • PUT /resources/:id to update a resource

We would like to allow a client to update a resource with its external ID. We thought about

  • PUT /resources/create_or_update/:external_id but we are not very satisfied with the name of the endpoint to say the least

Would you have an idea for a better name in lines with REST best practices?

kintso
  • 248
  • 5
  • 15
  • Maybe `PUT /resources/{the-id}?id-type={external|internal}`? – sp00m Jun 29 '18 at 09:31
  • 2
    "Best practices" would state that you shouldn't use verbs like `create` or `update` within your URIs though applications following the REST architecture don't really care how a URI is made up as long as it conforms to the [URI standard](https://tools.ietf.org/html/rfc3986). Similar to us humans, which prefer descriptive summaries of the link content within the relation name, applications are similar that they should use the link relation name to determine the intent of the URI rather than trying to parse the meaning of the link from the URI – Roman Vottner Jun 29 '18 at 09:32
  • Will you update/replace the completely full resource or just 1 or few of its fields? – Justinas Jakavonis Jun 29 '18 at 11:21
  • Because it is a PUT we will update the full resource based on the payload – kintso Jun 29 '18 at 11:37
  • Thanks @Denis.E. Your answer there is a good summary of the different solutions available – kintso Jan 28 '22 at 16:23

2 Answers2

2

Would you have an idea for a better name in lines with REST best practices?

REST doesn't care what spelling you use for your resource identifiers. (Demonstration: URL shorteners didn't break the web.)

If you have resources in two different hierarchies - one where you have complete autonomy for spelling, another where the clients have some control, then...

/09bce7a1-1f00-4bb4-8f72-8f642295a73e/:id
/8f3b9dc8-90de-48c5-aa96-a3f5a8d8e8ee/:external_id

... is fine.

You can choose any semantic spelling you like for the paths in the hierarchies.

Since REST doesn't care, you need to look somewhere else for guidance. Local coding conventions are a good starting point - but you probably wouldn't be asking if you already had such a thing to consult. Maybe marketing? perhaps they can make something from

/bronze/:id
/superUltraPlatinumPlus/:external_id
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
0

So at the end we decided to go for

PUT /resources/by_external_id/:external_id

It is the "least worst option" we came up with to update a resource based on a client reference. While it is still possible to update a resource with our reference:

PUT /resources/:id

As an answer suggested, we could have indeed went for 

PUT /resources/:external_id
PUT /resources/:id

But as external_id and id could use the same format (UUID), it might have impacted our performance (first check that the value doesn't exist as an id and if so check if it could be an external_id).

Also it was suggested in one of the comments, but we did not want to use a query parameter.

kintso
  • 248
  • 5
  • 15