REST API naming convention Best Practice for create or update a resource

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:

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

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

Maybe PUT /resources/{the-id}?id-type={external|internal}?
– sp00m
Jun 29 at 9:31

PUT /resources/{the-id}?id-type={external|internal}

"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. 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 at 9:32

create

update

Will you update/replace the completely full resource or just 1 or few of its fields?
– Justas
Jun 29 at 11:21

Because it is a PUT we will update the full resource based on the payload
– kintso
Jun 29 at 11:37

1 Answer
1

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


By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.