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:
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
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:
Then add the binary data itself:
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.
Use JSON as the Format for Sending and Receiving Data This is because, with XML for example, it's often a bit of a hassle to decode and encode data – so XML isn't widely supported by frameworks anymore.
A request body is usually a JSON document, and the structure of that JSON document can be defined in a Model. The structure of a request body is not currently validated by the IBM Integration Bus run time. However, the Model definition can be used with a Mapping node to graphically implement the REST API operation.
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With