REST Merge Resources - Multiple updates on PUT

Question

I do not believe this post fully answers the question.

Situation

• Endpoint exposes a single resource, Ids are unique.
• Names are unique but can change.
• External applications can and do store references to resource ids.

The problem

Sometimes duplicate resources are created and end up being referenced.

Solution

Expose an endpoint that allows resources to be "merged". This would do the following:

1. Mark 'xyz' (the resource being phased out) as being a duplicate of 'abc' (the resource being kept).
2. Update 'abc' to be what the merge resource should look like.
3. Any GET to retrieve 'xyz' will result in a 302 redirect to 'abc'

The Question

How would one do this restfully? I wanted to do something like:

PUT http://endpoint/resource/{id1}/merge/{id2}

{
    //new merged resource
}

Where id1 = the resource being kept and id2 = the resource being. Alternatively this could be visa versa if it makes more sense.

However my concern is that the act of merging will update both resources on a PUT. Does this break the rules and is there a better, prescribed way to do this?

Answer 1

In my opinion, the RESTful paradigm is great for giving people guidelines on how your API probably behaves, but forcing everything you can into it doesn't result in a better developer experience.

I would much rather see well-documented POST actions for everything beyond the standard four verbs. Here's my vote:

POST http://endpoint/resources/{id1}/merge
  {
     "merge_id": {id2}
  }

This also leaves you free to support a multi-id version, if that were commonplace.

POST http://endpoint/resources/{id1}/merge
  {
    "merge_ids": [
      {id2}, {id3}, {id4}
    ]
  }