In the last post you saw an overview of the Operations supported by the current version of my REST API for DocumentDB.

To get a better understanding of how to use these operation,  you need to see what are the required parameters.  Possible parameters in Swagger include Query, Path, Body, Header, and formData

Attachment Operations

Attachment Operation include:

  • Create an Attachment
  • Replace an Attachment
  • List Attachments
  • Delete Attachments
  • Query Attachments

Currently the my API only supports Get and Attachment and Create an Attachment.

If you read the DocumentDB REST documentation,  you know that Attachments are special documents that contain references with an external blob or media file.

NOTE:  Attachments are a preview feature in DocumentDB and has small limits for experimentation and development. For attachment storage quota information, see DocumentDB limits.

 

Get an Attachment

The following are the Operation Details.

Get attachment

Get an attachment


The following figure shows the Response Class model.

This is defined in the AttachmentRaw Definitions section in the Swagger as shown below. The required fields are ContentType and Slug. If you are interested in learning what these represent, you can view the documentation

AttachmentRaw:
    required:
      - ContentType
      - Slug
    properties:
      ContentType:
        type: string
        description: The content type of the attachment.
      Slug:
        type: string
        description: The name of the attachment
      User-Agent:
        type: string
        description: The client user agent performing the request
      id:
        type: string
        description: This is the attachment name and type.
      _rid:
        type: string
        description: This is a system generated property.
      _ts:
        type: string
        description: This is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.
      _self:
        type: string
        description: This is a system generated property.
      _etag:
        type: string
        description: This is a system generated property representing the resource etag required for optimistic concurrency control.
      _permissions:
        type: string
        description: This is a system generated property denoting the addressable path of the feed of permissions resource.
    description: 'POST the raw media in the body payload to store it in the provided attachment storage under your DocumentDB account.  To create this type of attachment, developers include the raw attachment (video, audio, file, blob, etc.) as the body of the POST. Two headers must be set: `Content-Type` and `Slug`. The Content-Type header is set to the MIME type of the attachment while the Slug header is set to the name of the attachment.'

Required Inputs

The required inputs are self-describing.  These inputs are generated from the Swagger as shown in the following figure. If I I added more details to the description for each input parameter, they would be included in the generated client code.

'//{rid-db}/colls/{rid-coll}/docs/{rid-doc}/attachments/{rid-attch}':
    get:
      tags:
        - Attachment
      summary: Get an Attachment
      description: Get an Attachment from document
      operationId: GetAttachement
      consumes:
        - application/json
      produces:
        - application/json
        - image/jpeg
        - application/dicom
      parameters:
        - name: rid-db
          description: The Database Id
          in: path
          required: true
          type: string
        - name: rid-coll
          description: The Collection ID
          in: path
          required: true
          type: string
        - name: rid-doc
          description: The Document ID
          in: path
          required: true
          type: string
        - name: rid-attch
          description: The Attachment ID
          in: path
          required: true
          type: string
        - name: Authorization
          type: string
          in: header
          description: 'The authentication type and signature token. Both master key and resource tokens are allowed for this operation. <c>type={typeoftoken}%26ver={tokenversion}%26sig={hashsignature}</c>'
          required: true
        - name: User-Agent
          type: string
          in: header
          required: false
          description: 'Optional. The string of client user agent performing the request. The recommended format is <c>{user agent name}/{version}</c>.'
        - name: x-ms-date
          type: string
          in: header
          required: true
          description: 'The date of the request The date is expressed in Coordinated Universal Time format.           example - <example>Fri, 08 Apr 2015 03:52:31 GMT</example>'
        - name: x-ms-version
          type: string
          in: header
          required: true
          description: The version of DocumentDB REST service. The latest version is used when the header is not provided use 2015-08-06
      responses:
        '200':
          description: The operation was successful
          schema:
            $ref: '#/definitions/AttachmentRaw'
        '400':
          description: The JSON body is invalid. Check for missing curly brackets or quotes
        '401':
          description: The Authorization or x-ms-date header is not set. 401 is also returned when the Authorization header is set to an invalid authorization token
        '403':
          description: The authorization token has expired. 403 is also returned by this operation when the number of permissions in the account has reached its allowable quota
        '409':
          description: The id or Slug provided for the new attachment has been taken by an existing attachment.
        '413':
          description: 'The document size in the request exceeded the allowable document size in a request, which is 512k'

Now, let’s take a look at Creating an Attachment.

Create an Attachment

NOTE:  This sample operation is based upon the attaching of Raw Media.  

The current version of the API supports the following Mime-Types

  • Application/Json
  • Image/Jpg
  • Application/Dicom
  • Image/Png

Additional mime-types can easy be added.

The following are the Operation Details. As you can see, it is self-describing.

create attachment

Create an Attachment

 

Required Inputs

The following is the Swagger (YAML) for the Create an Attachment operation

'/{rid-db}/colls/{rid-coll}/docs/{rid-doc}/attachments':
    post:
      tags:
        - Attachment
      summary: Create an Attachment
      description: Create an Attachment
      operationId: CreateAttachement
      consumes:
        - application/json
        - application/dicom
        - image/jpeg
        - image/png
      produces:
        - application/json
      parameters:
        - name: rid-db
          description: The Database Id
          in: path
          required: true
          type: string
        - name: rid-coll
          description: The Collection ID
          in: path
          required: true
          type: string
        - name: rid-doc
          description: The Document ID
          in: path
          required: true
          type: string
        - in: body
          name: Request
          required: true
          schema:
            $ref: '#/definitions/AttachmentRaw'
        - name: Authorization
          type: string
          in: header
          description: 'The authentication type and signature token. Both master key and resource tokens are allowed for this operation. <c>type={typeoftoken}%26ver={tokenversion}%26sig={hashsignature}</c>'
          required: true
        - name: User-Agent
          type: string
          in: header
          required: false
          description: 'Optional. The string of client user agent performing the request. The recommended format is <c>{user agent name}/{version}</c>.'
        - name: x-ms-date
          type: string
          in: header
          required: true
          description: 'The date of the request The date is expressed in Coordinated Universal Time format.           example - <example>Fri, 08 Apr 2015 03:52:31 GMT</example>'
        - name: x-ms-version
          type: string
          in: header
          required: true
          description: The version of DocumentDB REST service. The latest version is used when the header is not provided use 2015-08-06
      responses:
        '200':
          description: The operation was successful
          schema:
            $ref: '#/definitions/AttachmentResponse'
        '400':
          description: The JSON body is invalid. Check for missing curly brackets or quotes
        '401':
          description: The Authorization or x-ms-date header is not set. 401 is also returned when the Authorization header is set to an invalid authorization token
        '403':
          description: The authorization token has expired. 403 is also returned by this operation when the number of permissions in the account has reached its allowable quota
        '409':
          description: The id or Slug provided for the new attachment has been taken by an existing attachment.
        '413':
          description: 'The document size in the request exceeded the allowable document size in a request, which is 512k'

The following figure shows the Response Class model.

create attachment detail

Attachment Response Details

This is defined in the AttachmentResponse Definitions section in the Swagger as shown below. The required fields are id and Slug. If you are interested in learning what these represent, you can view the documentation

Request Body

The following figure shows the Body for the Request Parameter.

Request body schema

A sample is shown below.

Request body schema sample

I you “click” in the sample data shown on the right, it will populate the Request body as shown above.
The Swagger definition is shown in the following figure.

AttachmentResponse:
    required:
      - Media
      - contentType
      - id
    properties:
      id:
        type: string
        description: 'This is a user settable property. It is the unique name that identifies the attachment, i.e. no two attachments share the same id. The id must not exceed 255 characters. The value set in Slug is recorded here'
      contentType:
        type: string
        description: This is a user settable property. It specifies the content type of th  attachment.
      Media:
        type: string
        description: This is the URL link or file path where the attachment resides.
      _rid:
        type: string
      _ts:
        type: string
      _self:
        type: string
      _etag:
        type: string
    description: Attachments are special documents that contain references and associated metadata with an external blob or media file.

In the next post we will take a look at Collections.