Rest API designing PUT vs PATCH

Question

I am developing 2 REST APIs which edits and pause something at my backend. For editing I was using:

PUT /video/1

What is the best way to develop a pause video service. Should I use PATCH or PUT for this? Input would be just the id. If I use PUT then how can differentiate between edit and pause? And if I have another API to be developed for eg: video restart how can I accommodate these verbs in REST API?

Answer 1

Distinguishing the state using the HTTP method only is a poor idea. What you can is to:

1. Introduce state, and then use PATCH to change the state:

   PATCH /vidoes/1
   {
      "state": "PLAYING|PAUSED|STOPPED" // what you need here
   }
   

Mind don't patch like an idiot, however it is common to patch like an idiot.

2. Introduce new endpoints that will reflect the operation invoked on the resource - this is not fully RESTful, however also common:

   POST /vidoes/1/play/
   POST /vidoes/1/stop/
   POST /vidoes/1/pause/
   

PUT for editing is ok of course, however remember that PUT is idempotent and requires the resource to be sent.

Answer 2

I do not agree with @Opal's answer here hence I post this answer. I do feel you use the wrong tools (or terms) to achieve what yo want. REST is more then just a HTTP invocation via a cleanly designed URI. As proposed by @Opal in a comment on his answer, WebSockets might be what you are looking for, though REST may be able to server your needs as well (as plain HTTP would do either).

Pausing a video

It should not be the task of the HTTP server to stop the video but the client. Usually partial GET requests are sent to the server retrieving only a portion of the resource and adding them to a buffer which the client reads. In the back the client site will issue further partial requests to keep the buffer filled while the client is reading it. If the client wants to pause, it simply stops reading the buffer and optionally stop sending further partial GET requests to the server.

This allows to spread the actual video onto mutliple servers and let the client talk to any of these and still get the correct responses. If the server has to maintain the client state, you need to ensure that the state is also replicated to all the other serving nodes. Sure, this is possible but also combined with higher overhead!

Updating videos

As you obviously create a video-editing system you have two options here as also suggested by the PUT definiton:

Partial content updates are possible by targeting a separately identified resource with state that overlaps a portion of the larger resource, or by using a different method that has been specifically defined for partial updates (for example, the PATCH method defined in RFC5789).

• Separate the resource into smaller resources
• Use an other method like PATCH

As already pointed out by @Opal in his answer, in case when you use PATCH to partially update a resource you should not only provide the new content within the body but also instruct the server what is should do with it.

The separation into smaller resources however does feel more natural to me for a video-editing system though. A video can be seen as a sequence of scenes which consist of numerous pictures and maybe an attached soundfile.

A movie therefore could be represented like this in pseudo Json-HAL:

Movie : {
    title: The Matrix,
    release_year: 1999,
    actors: [Keanu Reeves, Laurence Fishburne, Carrie-Anne Moss, Hugo Weaving, Joe Pantoliano],
    ...
    link: {
        self: http://...,
        ...
    },
    embedded: {
        Scenes : [
            {
                description: Trinity chased by police,
                links: [
                    self: http://...,
                    video: http://.../scene01.vid
                ]
            },
            {
                description: Thomas Anderson get notified to follow the white rabbit,
                start_offset: 5091,
                end_offset: 193920,
                links: [
                    self: http://...,
                    video: http://.../scene02.vid
                ]
            },
            ...
        ]
    }
}

Instead of having all the bytes in one file you could maintain each scene separately. The movie representation combines the scenes to a full movie if played from scene 1 to scene n.

If now one scene is edited and the whole scene file should be replaced, using a simple PUT request is enough. If you want to trim the first or last few seconds off the video, you could introduce a start and stop offset for the respective scene and instead of reuploading the full scene again, you tell the client that it should start at the suggested offest or stop at the suggested position.

The client can use this parameters in the partial GET request to retrieve only the necessary bytes. This fields should then of course be modified via a PATCH command in order to prevent altering the video bytes or its URI. In order for a client to learn the total bytes of a video it can issue a HEAD request first to the URI and use the content length returned from the response

This, of course, screems for its own media-type, but this is what REST is actually all about. I don't know why so many misuse the REST-term for plain URI-design or think that a neat URI-API is more RESTful when REST doesn't care much about the URI layout actually.