Doc.Build API

Doc.Build is a document toolkit that can store, retrieve and perform actions on a document. The API is RESTful and requires no dedicated client-side libraries, only access to the web.


Public API

You're able to reach the public API for doc.build at

http://api.doc.build/

Input Format

This service can accept JSON, HTTP forms and XML requests. In this documentation we will use HTTP forms. The response type will follow the Accept header. Below is an example in JSON:

    curl -i \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -d '{"document":{"name":"Test File 1","extension":"docx"}}' \
        http://api.doc.build/documents

Authentication

All resource endpoints are protected with OAuth2. You are required to provide an access token with each request.

Requesting an access token

You must use the OAuth2 client_credentials grant type to get an access token to be used with the public doc.build API.

You can create a client by registering on the doc.build website at http://doc.build/signup.

The URL used to request an access token is http://api.doc.build/oauth/token.

Example

Request
    curl -i \
        -X POST \
        -H "Accept: application/json" \
        -F grant_type="client_credentials" \
        -F client_id="myClientID" \
        -F client_secret="myClientSecret" \
        http://api.doc.build/oauth/token
Response
{
    "access_token": "MmE1NWE5MTQ5YjQ4ODNhN2FkY2Qjg4MDY3Mg",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null
}

Using an Access Token

A valid access token is required by all API endpoints. You can pass the access_token as a request parameter.

Example

Request
    curl -i \
        -H "Accept: application/json" \
        -F access_token="MmE1NWE5MTQ5YjQ4ODNhN2FkY2Qjg4MDY3Mg" \
        http://api.doc.build/documents/a1ec0371-966d-11e4-baee-08002730eb8a

Handling an expired access token

In the event that an access token becomes invalid - e.g. it times out - an error will be returned by the API endpoint.

{
    "error": "invalid_grant",
    "error_description": "The access token provided has expired."
}

In this case, to continue using the API, you must request a new access token using your client credentials.

Once a new access token has been obtained, the failed request should be retried with the new access token.


Documents

Documents can be stored into the system either with or without uploading their contents (referred to in the API as the payload). If a document does not have a binary payload then it is possible to upload the payload at a later date. Actions will not be triggered until the payload is uploaded.

Please note that once a document has a payload attached, that payload will become immutable and can no longer be updated.

Creating a document

In this example we are sending data over in HTTP forms with the payload as we need multi-part functionality.

Request
    curl -i \
        -X POST \
        -H "Accept: application/json" \
        -F document[name]="Test Document 1" \
        -F document[extension]="docx" \
        -F document[file]=@TestFile1.docx \
        http://api.doc.build/documents
Response
   {  
      "status":"pending",
      "id":"a1ec0371-966d-11e4-baee-08002730eb8a",
      "name":"Test Document 1",
      "extension":"docx"
   }

Listing documents

Request
    curl -i \
        -H "Accept: application/json" \
        http://api.doc.build/documents
Response
[  
   {  
      "status":"pending",
      "id":"a1ec0371-966d-11e4-baee-08002730eb8a",
      "name":"Test Document 1",
      "extension":"docx"
   }
]

Retrieving a single document

Request
    curl -i \
        -H "Accept: application/json" \
        http://api.doc.build/documents/a1ec0371-966d-11e4-baee-08002730eb8a
Response
   {  
      "status":"pending",
      "id":"a1ec0371-966d-11e4-baee-08002730eb8a",
      "name":"Test Document 1",
      "extension":"docx"
   }

Payload/Contents

Uploading a document contents (payload)

Documents can be without a payload, for example if you create a holding place for a document before the document has been created. In cases like this it is possible to upload the document payload after it has been created.

Please note that once a document has a payload attached, that payload will become immutable and can no longer be updated.

Request
    curl -i \
        -X POST \
        -H "Accept: application/json" \
        -F document[file]=@TestFile1.docx \
        http://api.doc.build/documents/a1ec0371-966d-11e4-baee-08002730eb8a/payload
Response

HTTP/1.1 204 No Content Location: http://api.doc.build/documents/afe041c3-9a6c-11e4-baee-08002730eb8a

Download a document's contents

Request
    curl -i \
        -H "Accept: application/json" \
        http://api.doc.build/documents/a1ec0371-966d-11e4-baee-08002730eb8a/payload
Response
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename="TestDocument1.docx
<BINARY DATA>

Document Actions

Combining PDFs in to one

The location of the new combined document is returned in the header key "Location". Please note this will not be available until the action has been completed. You can either poll the location for an update or use the callback action to notify you.

Request
    curl -i \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -d '{"name":"Combined Document 2","source":{"id":"a1ec0371-966d-11e4-baee-08002730eb8a","id":"a1ec0371-966d-11e4-baee-08002730eb8a"},"callback":"http://localhost/test/callback?id=a1ec0371-966d-11e4-baee-08002730eb8a"}' \
        http://api.doc.build/combined
Response
    HTTP/1.1 202 Accepted
    Location: http://api.doc.build/documents/65a3640d-9825-11e4-baee-08002730eb8a

Converting documents

The location of the new pdf converted document is returned in the header key "Location". Please note this will not be available until the action has been completed. You can either poll the location for an update or use the callback action to notify you.

Request
    curl -i \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -d '{"source":"a1ec0371-966d-11e4-baee-08002730eb8a","callback":"http://localhost/test/callback?id=a1ec0371-966d-11e4-baee-08002730eb8a"}' \
        http://api.doc.build/pdf
Response
    HTTP/1.1 202 Accepted
    Location: http://api.doc.build/documents/65a3640d-9825-11e4-baee-08002730eb8a

Callbacks

Requesting a callback

A callback will be triggered whenever the state of a document changes, once the callback has been processed and accepted it will not be triggered on further updates. If a callback is not successful a exponential backoff approach will be used until either the callback has been accepted or the callback has timed out.

Request
    curl -i \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -d '{"source":"a1ec0371-966d-11e4-baee-08002730eb8a","url":"http://localhost/test/callback?id=a1ec0371-966d-11e4-baee-08002730eb8a"}' \
        http://api.doc.build/callback
Response
    HTTP/1.1 204 No Content