diretto Storage APIv2 - Draft
TOC

diretto Storage API

Introduction

Version

v2 - Draft

Author

Benjamin Erb

Description

The Storage API is responsible for the reception, storage and delivery of submitted attachments of documents. The Storage API is designed to support HTTP mechanisms like caching and conditional GETs for improved performance.

Authentication Schemes

Base URI

http://storage.example.foo/

Index of Resources and Operations

  1. Attachment
    1. Download an attachment
    2. Retrieve attachment's meta data
    3. Upload a new attachment (using POST)
    4. Upload a new attachment (using PUT)
  2. Index
    1. Get static information

1. Attachment

Description

An attachment is a media file that belongs to an abstract document. Each document owns one or more attachments. The first attachment should be considered as the "original" item, while all additional attachments represent derivated or customized versions. General Upload Flow: 

   Client         Core API Server      Storage API Server

     |                    |                   |
     |                    |                   |
     | (1) POST Metadata  |                   |
     |------------------->|                   |
     |                    |                   |
     | (2) 202 + Location |                   |
     |<-------------------|                   |
     |                    |                   |
     | (3) PUT/POST Entity (signed URI)       |
     |--------------------+------------------>|
     |                    |                   |
     | (4) 201 Created + Accept Key in Body   |
     |<-------------------+-------------------|
     |                    |                   |
     | (5) DELETE Lock (via Accept Key)       |
     |------------------->|                   |
     |                    |                   |
     | (6) 204            |                   |
     |<-------------------|                   |
     |                    |                   |
     |                    |                   |

Resource URI

http://storage.example.foo/{document-id}/{attachment-id}.{attachment-ext}
document-id
document ID
attachment-id
attachment ID
attachment-ext
attachment extension

1.1 Download an attachment

Description

This operation allows to download an existing attachment. Conditional GETs must be supported by the storage server. Clients should support caching and dispatch conditional requests whenever possible.

URI

http://storage.example.foo/{document-id}/{attachment-id}.{attachment-ext}

URI Parameters

document-id
document ID
attachment-id
attachment ID
attachment-ext
attachment extension

HTTP Method

GET

Resource Formats

Authentication

not required

Request Entities

n/a

Responses

200 OK
Attachment in response entity
304 Not Modified
Cache hit (conditional request)
403 Forbidden
The requested resource URI is not allowed
404 Not Found
Attachment and/or document not found
500 Internal Server Error
Internal error while streaming the attachment

Response Entities

n/a

1.2 Retrieve attachment's meta data

Description

A HEAD request against an attachment allows to retrieve several meta data. Servers must provide the following HTTP headers: Content-Type (mime type), Content-Length (file size) and ETag (caching identifier). This operation should also be used for checking the existence of an attachment.

URI

http://storage.example.foo/{document-id}/{attachment-id}.{attachment-ext}

URI Parameters

document-id
document ID
attachment-id
attachment ID
attachment-ext
attachment extension

HTTP Method

HEAD

Resource Formats

Authentication

not required

Request Entities

n/a

Responses

200 OK
Attachment exists, contents omitted
304 Not Modified
Cache hit (conditional request)
403 Forbidden
The requested resource URI is not allowed
404 Not Found
Attachment and/or document not found
500 Internal Server Error
Internal error while streaming the attachment

Response Entities

n/a

1.3 Upload a new attachment (using POST)

Description

New attachments must be uploaded to the storage server as part of a three-part workflow. First, meta data must be sent to the API server. When the API server grants the creation of a new attachment, it also provides an access token that is needed for the actual upload against the storage server. Without a valid access token, no upload can be performed. On succcessful upload, the storage server also creates a token that must be sent to the API server to approve the upload process. Unlike the PUT-based upload call, this method uses a POST multipart call as known from HTML-based upload forms. The following HTML snippet shows an equivalent HTML form for dispatching such a request: 
<form action="http://mediaserver/0ecb3c6f-9ed9-41d0-ae40-ea074aeb1786" enctype="multipart/form-data" method="post">
  <input type="text" name="token" value="28e1095e0cec3f6e06c85fb14a52f90e3f9a6127" />
  <input type="text" name="filename" value="b54adc00-67f9-11d9-9669-0800200c9a66.jpg" />
  <input type="file" name="upload" />
  <input type="submit" value="Upload" />
</form>
Please note that the URI as well as the values are examples and must be replaced.

URI

http://storage.example.foo/{document-id}

URI Parameters

{document-id}
document ID

HTTP Method

POST

Resource Formats

Authentication

required

Request Entities

n/a

Responses

201 Created
The attachment has been created
400 Bad Request
The upload has been rejected (i.e. due to invalid file size)
401 Unauthorized
Wrong or invalid credentials
403 Forbidden
The targeted path or the provided access token is invalid
409 Conflict
The media file already exists
411 Length Required
Upload failed due to missing Content-Length information
500 Internal Server Error
Internal server error while handling the upload

Response Entities

{
	"successToken" : "9365929d8479d2ca39826878984ff5f2b70b5d65"
}
In case of a successful upload (201), a response key is provided that must be send to the API server in order to prove the upload. 
{
	"error" : "The attachment size exceeds the server limits for uploads"
}
Otherwise, an error message is available as entity.

1.4 Upload a new attachment (using PUT)

Description

New attachments must be uploaded to the storage server as part of a three-part workflow. First, meta data must be sent to the API server. When the API server grants the creation of a new attachment, it also provides an access token that is needed for the actual upload against the storage server. Without a valid access token, no upload can be performed. On succcessful upload, the storage server also creates a token that must be sent to the API server to approve the upload process. This operation does not support chunked uploads and the following request headers are mandatory: Content-Type (mime type), Content-Length (file size) and authentication. The actual media file must be provided as it is in the request entity. Please note that creating an initial attachment includes creating a document itself. Thus, the first API call slightly differs, because a PUT against the targeted document location is required instead of a POST. The complete flow is listed here:

URI

http://storage.example.foo/{document-id}/{attachment-id}.{attachment-ext}?token={token}

URI Parameters

document-id
document ID
attachment-id
attachment ID
attachment-ext
attachment extension
{token}
access token

HTTP Method

PUT

Resource Formats

Authentication

required

Request Entities

n/a

Responses

201 Created
The attachment has been created
400 Bad Request
The upload has been rejected (i.e. due to invalid file size)
401 Unauthorized
Wrong or invalid credentials
403 Forbidden
The targeted path or the provided access token is invalid
409 Conflict
The media file already exists
411 Length Required
Upload failed due to missing Content-Length information
500 Internal Server Error
Internal server error while handling the upload

Response Entities

{
	"successToken" : "9365929d8479d2ca39826878984ff5f2b70b5d65"
}
In case of a successful upload (201), a response key is provided that must be send to the API server in order to prove the upload. 
{
	"error" : "The attachment size exceeds the server limits for uploads"
}
Otherwise, an error message is available as entity.

2. Index

Description

The index resource provides static information about the deployed service.

Resource URI

http://storage.example.foo/

2.1 Get static information

Description

This operation allows to receive static information about the deployment. HEAD requests against this resource may be useful to check the service's availability.

URI

http://storage.example.foo/

URI Parameters

n/a

HTTP Method

GET

Resource Formats

Authentication

not required

Request Entities

n/a

Responses

200 OK
Service information in response entity

Response Entities

{
   "api":{
      "name":"org.diretto.api.main.storage",
      "version":"v2"
   },
   "service":{
      "name":"diretto Storage Node",
      "version":"0.2.0"
   },
   "deployment":{
      "title":"fubar Storage Service",
      "contact":"n/a",
      "website":{
         "link":{
            "rel":"self",
            "href":"http://www.diretto.org"
         }
      }
   },
   "direttoMainServices":{
      "core":{
         "link":{
            "rel":"self",
            "href":"http://core.example.foo/v2"
         }
      }
   },
   "links":[
      {
         "title":"diretto Storage API Documentation",
         "link":{
            "rel":"self",
            "href":"http://diretto.github.com/diretto-api-doc/v2/diretto/storage.html"
         }
      }
   ]
}