Designing a REST service for media conversion

My current task is to design a REST service that can be used to convert from one media type to another (e.g. from video/x-msvieo to video/x-flv). Its not supposed to be usable vie Browser. Generally, I'll let clients POST media files and return them some URL for further reference (like http://www.example.com/Media/12345).

Interesting thing is - and that's where questions arise - that the conversion process could be interpreted in two different ways:

1) A converted media is simply a different representation of the original one, so to request a media in a new format, you could just GET http://example.com/Media/12345, and tell the service in the Accept-header what format you need. Since converting for example a big video, the service would respond with a 202 Accepted until conversion has finished. But what should happen, if the conversion fails for any reason开发者_开发问答?

2) Since conversion takes such a long time, one could represent the process as its own resource. In this case, one would have to POST some form of job description (probably xml) to http://example.com/Media/12345 and the service would respond with a new URI for the requested conversion (like http://example.com/Media/12345/jobs/1). But wouldn't this kind of design be quite non-REST-linke?

What I currently have is this:

1.) POST media file to http://example.com/Media

2.) Response: 201 Created / Location: http://example.com/Media/12345

3.) GET http://example.com/Media/12345

4.) Response: 200 Ok and xml like this:

<media id="123457">
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://example.com/Media/12345/video/x-flv">video/x-flv</link>
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://example.com/Media/12345/video/mpeg">video/mpeg</link>
</media>

The links in the xml send you to conversion targets available for this media.

5.) Select from the links in the xml to start a conversion / get the result by GETting http://example.com/Media/12345/video/mpeg

6.) Response: 202 Accepted / Location: http://example.com/Media/12345/video/mpeg/Status

7.) Repeat step 5 until conversion is done or have a look at the http://example.com/Media/12345/video/mpeg/Status to see what currently happens.

So, thanks a lot for reading all this stuff :)

What do you think about my approach? What would you do differently?

I am quite new to this stuff, so any suggestions are highly appreciated.

kind regards: Bill

---

In step 4 I would consider using a 300 response code. You are doing something very similar to client driven content negotiation. See how it's done here http://www.w3.org/TR/wd-xptr

Your idea to create a "job" resource to represent the creation of the new media file is a perfectly valid and very common approach to handling long running operations in RESTful systems.

The only other comment is that in step 5, I was initially concerned about using GET to do that, but having thought about it a bit more it does seem reasonable. It's nice because the the final converted video can be made available at the same URL. Then all the client has to do is be aware of the fact that if they request a video and they get a 202, they just have to wait a bit before retrying. If they want, they can check the ./status resource to know if it done. I guess you just have to make sure if you are already in the process of converting you return another 202 but don't start a new conversion process :-)

---

Yes, the redirect (presumably) to http://example.com/Media/12345/jobs/1 doesn’t sound very restful. It sounds like you are trying to implement an asynchronous service through a synchronous interface. Couldn’t you POST a ‘conversion request’ resource to kick the process of that returns a session, i.e. a bit like:

Class ConversionRequest
{
 Guid sessionid
  Int status
…
}

Then use a GET/sessionId to check the status of the conversion? In my experience, if a restful interface starts to feel complex it generally means the resource isn’t right for the task in hand.

---

You approach seems fine. You can encode any concept in your URIs which obviously includes the jobs concept. It all depends on how you want to design your application interface (resources).

Here is one way I would attack it and it might give you some ideas. (It depends on your clients and application protocol / interface :

• /media
  • GET - List of media + status etc.
  • POST - Add medias + returns Location: /media/{number}/jobs/{number}
• /media/{number}
  • GET - Shows media status (Valid,In Progress), formats etc. Links to default/current jobs
• /media/{number}/jobs
  • GET - List of jobs
  • POST - Do extra/special conversion
• /media/{number}/formats/{name}
  • GET - Download
  • PUT - Start specific conversion, redirects to a job.
• /media/{number}/jobs/{number} - Job status etc.
  • GET - Status etc,
  • DELETE - Cancel job

Remember that PUT and DELETE is idempotent and POST not.

The way you make use of hypermedia and links looks good. The client should discover the next step or related information via links and not rely on out of band information such as URI structure.