What is an Attachment?

Here's our current definition of an attachment:

• A resource that is related to another resource and adds supplemental information

Examples of Attachments:

• A screen-shot attached to a Change Request
• An office document attached to a Requirement

How should attachments work?

Attachments are Resources. A Resource links to its Attachments.

• Attachment should be created via POST
• Attachment should have URI
• Resource should link to its Attachments

Domain specs will define their own attachment property name.

Use case #1: Consumer associates Attachment with Resource

The consumer does the work: creating the Attachment if necessary and adding the link to the Resource being attached to. The Consumer may create Resource via POST (as shown below) or Consumer may use an existing Resource as the Attachment, if the Provider allows that. Provider may require that all Attachments be created via Provider's Creation Factory, thus disallowing use of existing Resources.

There should be nothing new here. This is how you'd expect things to work with HTTP and RDF.

WebSequence Diagrams notation for this interaction:

Consumer->Service: POST attachment to be added
Service->Consumer: gets back URI of attachment 
Consumer->Resource: GET resource to be attached to 
Consumer->Resource: PUT back resource with new link to attachment

Use case #2: Consumer displays Resource and list of Attachments

Consumer can display Resource and list of attachments because, in addition to links to Attachments, Resources may contain:

• Property values which are links to Attachments
• Property values about the Attachments
• Property values about the Attachments links

Either a Provider or a Consumer may add those properties. A Consumer knows which property values are links to Attachments and how to find properties about each, so it can easily display a list of Attachments. Again, there should be nothing new here either, just HTTP and RDF.

Use case #3: Consumer gets and updates an Attachment

In this use case, the Consumer gets a Resource, picks the Attachment to update, gets the Attachment and then puts back the updated Attachment. For example, here a Consumer gets and updates an image Attachment.

WebSequence Diagrams notation for this interaction:

Consumer->Resource: GET
note left of Consumer: picks Attachment URI
Consumer->Attachment: GET on Attachment URI
Attachment->Consumer: sends back Attachment
note left of Consumer: edits Attachment image
Consumer->Attachment: PUT new image
Consumer->Resource: PUT with updated properties about Attachment