• REST Resources
• Representations
• API Key Authentication
• Property Types
• Filters
• Parameters
• HTTP Requests
  
• HTTP Status Codes
• Error Messages

REST Resources

We've attempted to make the Doculicious API adhere to the REST architecture. This means that the "things" within Doculicious, such as your templates and the entries made to them are represented as resources that have a unique URI and one or more representations defined by the file extension used to call the resource. Resources can be collections of other resources, in which case you can access an individual resource by calling its UID after the collection resource, ie:

https://api.doculicious.com/<resource-collection>/<resourceUID>.<representation>

• <resource-collection>: This is a collection of resources, such as entries or templates. eg /do/api/templates, /do/api/entries
  
• <resourceUID>: This is the Unique ID (UID) of an individual thing you are requesting. Eg: it could be the unique ID of a Template or Entry.
• <representation>: How you want the result returned. See below...

Representations

A representation is the format that you want to retrieve a particular resource in. For example, many Doculicious resources can be viewed as documents, such as printable PDF files made from a template, but these resources are also individual pieces of data that can be represented in text formats such as XML, CSV or HTML, or image formats like JPG. Representations allow you to choose different ways to work with the data in your account.

Each resource and method combination may support different representations, and this will be outlined in the relevant description of each resource. Doculicious supports text based formats such as XML, JSON and HTML and also binary formats like PDF.

XML is the default representation for all resources, but you can easily change this by providing an extension when you call a resource, such as .json or .pdf. The resource section of this help documentation describes the available representations.

A note on JSON representations

JSON does not have an inherent way to include meta-data about elements it is modelling, such as XML does with attributes. To ensure that our JSON and XML representations are as compatible as possible, elements that would contain an attribute if output as XML, will be represented as a JSON object with the attributes as single fields in the object, each preceded with the "@" sign, and the actual value or data of the element in a field called "$". Here's an example:

XML
<value class="string">The Value</value>

JSON
{
  "@class":"string",
  "$":"The Value"
}

API Key Authentication

Most Doculicious API calls will require the caller to identify and authenticate themselves before access to a resource is given. Each Doculicious account has an API Access ID and an API Secret Access Key that act as a username and password to the API. When you send a request to act on a resource, you must provide the ID and the Key. This can be sent in one of two ways, in the header or in POST form variables.

PLEASE NOTE: all API requests MUST use SSL so that this information is secured. So the URL should always begin with:

https://api.doculicious.com/

Any calls to http://api.doculicious.com will return an error

Header Authentication

You can send the API ID and API Key in the authorization header of the request by including the following header:

authorization: DCS APIAccessID:APISecretAccessKey

POST Variable Authentication

You may also send the authentication information using POST variables. This allows you to use a HTTP form post to submit details to a resource. To do this, use the following form fields:

_apiAccessId=<APIAccessID>
_apiAccessSecretKey=<APISecretAccessKey>

Security Note: Please ensure that you use HTTPS so your request is sent through a secure connection, and don't hardcode your API Access Secret Key into web forms. 

Optional Authentication

With some API calls, authentication is optional and can be turned on or off for individual templates. The "api" section of a templates dashboard entry will contain checkboxes to enable/disable the security for certain methods. If the checkbox is "checked", security is enabled for that method, and the authentication procedures documented above must be implemented. If the checkbox is off, no authentication is needed.

Why would I want the security off?
Sometimes there is no security risk to allow a method to be called without authenticating the the caller. For example, when creating new entries for a specific template that should be publicly accessible. By not requiring authentication, it's easy to create a simple HTML web form that can submit directly to this method, without the need to proxy the request and add authentication details when they're not really needed.

Property Types

 Resources are made up of different properties, each of which is of a certain type. The types are described below:

Filters

As stated previously, resource collections can be filtered on the properties of the individual resources that make up the collection. Each of these properties is of a certain type, and each type has different filter conditions that can be used. Below is an outline of these types and their valid conditions. Each resource will state which of its properties can be filtered on, and what type the property is.

Multiple filters can be used for a single property, for example you could do this to retrieve values between two dates:

http://api.doculicious.com/entries/{template_uid}.xml?createdDate__gte=2009-04-23T21:34:23%2B10:00&createdDate__lte=2009-04-23T21:34:24%2B10:00

Note: The plus ("+") sign needs to be HTML encoded to "%2B" for use in the URL.

Filtering collections

Resource collections can be filtered by providing values for the properties of the resources you want returned. Ie: The Doculicious Element resource has a property called "readOnly" that can be true or false. To retrieve all the Elements flagged as read only from a Template collection you can call:

https://api.doculicious.com/templates/<template_uid>/elements.xml?readOnly=true

To retrieve only writable elements, change readOnly=true to readOnly=false. To retrieve all the elements of the collection, leave out the filter. Multiple filters can be joined together to filter the collection more. Read more on filters here.

Each resource collection will describe which properties can be filtered on.

Filtering sub-collections

If a resource has a collection of resources within it, you may be able to filter the sub-collection using filters and parameters. To do this, you use "dot notation" to reference the collection and parameter or filter you want to filter on. For example, the entries resource contains a sub-collection of elements within each entry. You can pass the parameter value elements._rows=10 to limit that collection to 10 rows. You could also pass through the filter elements.readOnly=false to limit the collection to only elements that are not set as read only. The resources help documentation will outline which sub-collections can be references this way, and which fields are applicable.

Limiting how many records a sub-collection returns can be used to decrease the size of your requests. If you don't need the sub-collections you can set the _rows value to 0 and none will be returned, or you can filter to only retrieve the records that are required for your query. Some resources will automatically filter their sub-collections, such as the entries resource, which only retrieves the elements within each entry that are not read only - as these elements are the only ones within an entry that can have user inputed data.

Parameters

Some resource URI's allow parameters to be passed which will effect the response in some way. We've already mentioned Authorisation, and how you can send the APIAccessID and APIAccessSecretKey as form fields in a POST request, but there are other paramaters that can be sent when calling a collection resource or an individual resource.

The parameters will be flagged in the resource help section as Parameters as opposed to Filters. Parameters always begin with an underscore "_". Here are some of the current parameters available:

HTTP Requests and Methods

Using the Doculicious API is a simple matter of making HTTP requests to different resources using the standard HTTP methods. Below is a list of the available methods and what they mean when used with the Doculicious API:

Using POST for DELETE or PUT

Some clients do not support the use of the DELETE or the PUT methods. A work around we've implemented is the use of the POST method with a query string containing _method=put or _method=delete. Our system will then convert to the stated method.

HTTP Status Codes

Each request you make to the Doculicious API will recieve a particular HTTP status code upon completion.  The table below lists them all:

Error Messages

If an API request results in an error, the HTTP reply will:

• contain an error resource that is in the format specified by the request. If format is invalid or not JSON or XML the error message will be in JSON format.
• have a Content-Type appropriate for the format requested. If the format is invalid, the Content-Type will be text/plain.
• contain an appropriate 3xx, 4xx, 5xx HTTP status code.

List of error codes

Here are some examples of error responses:

XML

JSON