RESTful design - how to model entity's attachments

Question

I am trying to model entity's attachments in REST. Let's say a defect entity can have multiple attachments attached to it. Every attachment has a description and some other properties (last modified, file size...) . The attachment itself is a file in any format (jpeg, doc ...)

I was wondering how should I model it RESTfully

I thought about the following two options:

First approach (using same resource, different representations):

• GET , content-type:XML on http://my-app/defects/{id}/attachments will return the defect's attachments metadata in XML format (description, last modified, file size...)

• GET , content-type:gzip on http://my-app/defects/{id}/attachments will return the defect's attachments in a zip file

• GET , content-type:mime multi-part on http://my-app/defects/{id}/attachments will return the defect's attachments in a multi-part message (binary data and XML metadata altogether)

• POST, content-type:XML on http://my-app/defects/{id}/attachments will create new attachment, metadata only no file attached (then the user has to send PUT request with the binary data)

• POST , content-type:mime\multi-part on http://my-app/defects/{id}/attachments will create the attachment, the client can send both metadata and file itself in a single roundtrip

Second approach (separate the attachment's data from the metadata):

• GET , content-type:XML on http://my-app/defects/{id}/attachments will return the defect's attachments metadata in XML format (description, last modified, file size...)

• GET , content-type:gzip on http://my-app/defects/{id}/attachments/files will return the defect's attachments binary data in a single zip

Creating a new attachment, first call:

• POST, content-type:XML on http://my-app/defects/{id}/attachments will create new attachment, metadata only no file attached (then the user has to send PUT request with the binary data)

Then add the binary data itself:

• POST , content-type:mime\multi-part on http://my-app/defects/{id}/attachments/{id}/file will create the attachment file

---

On one hand the first approach is more robust and efficient since the client can create\get the attachments metadata and binary data in single round trip. On the other hand, I am a bit reluctant to use the mime-multipart representation as it's more cumbersome to consume and produce.

EDIT: I checked out flicker upload REST API. It seems they are using multi part messages to include both the photo and the photo attributes.

Answer 1

Don't manage metadata separately. A two-part action defeats the point of REST.

One smooth GET/POST/PUT/DELETE with one -- relatively -- complex payload is what's typically done.

The fact that it's multiple underlying "objects" in "tables" is irrelevant to REST.

At the REST level, it's just one complex object's state transmitted with one message.

Answer 2

Much of this problem has already been solved by the Atom Pub spec. See here

One thing to be careful about in your proposed solutions is that you are using content negotiation to deliver different content. I believe that is considered bad. Content negotiation should only deliver different representations of the same content.