- Your Account
- Getting Around
- How To
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:
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.
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:
<value class="string">The Value</value>
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:
Any calls to http://api.doculicious.com will return an error
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
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:
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.
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.
Resources are made up of different properties, each of which is of a certain type. The types are described below:
|String||A text value made up of characters. If the representation is XML, any special characters will be HTML encoded. ie, the "<" and ">" characters become < and >|
|Integer||A value from 0 to 9.|
|Boolean||A value of True or False.|
|Timestamp||A date & time format. Dates passed to Doculicious must match this format exactly - YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00).
Note: When passing dates to the API via the URL you will need to encode them.
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.
|Equal To (=)||(None)||Boolean
|Greater Than or Equal To (>=)||__gte||Timestamp
|Less Than or Equal To (<=)||__lte||Timestamp
Multiple filters can be used for a single property, for example you could do this to retrieve values between two dates:
Note: The plus ("+") sign needs to be HTML encoded to "%2B" for use in the URL.
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:
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.
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.
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:
|_rows||Collection Resources||How many rows of data to return per page|
|_page||Collection Resources||Which page of data to return.|
|_hideLinks||All resources||Hides all navigation links in resulting resources.|
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:
|GET||Use to retrieve the resource that is identifed by the request URI. This can be a particular entry made to one of your templates, a template itself or a list of elements that make up a template.|
|POST||Use to add a new resource to a collection of resources. For example, to add a new entry for a particular template, you would POST to the entries collection URI for a specific template.|
|DELETE||This method is used to delete a particular resource.|
|PUT||Is used to update a specific resource with a new value. It will completely replace the old value with the new value.|
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.
Each request you make to the Doculicious API will recieve a particular HTTP status code upon completion. The table below lists them all:
|Code||Name||Description||What will return this?|
|200||OK||The request has succeeded.||
|201||Created||The request has been fulfilled and resulted in a new resource being created.||
|400||Bad Request||Some part of the request you made was incomrehensible to the server.||
|403||Forbidden||There was a problem authenticating your request.|
|404||Not Found||The requested resource could not be found.|
|405||Method Not Allowed||The method used is invalid for the resource.|
|500||Internal Server Error||We caused an error.|
|501||Not Implemented||The resource and method you requested have not yet been implemented.|
If an API request results in an error, the HTTP reply will:
Here are some examples of error responses:
|Error Code||HTTP Status Code||Message|
|AccessDenied||403 - Forbidden||Access Denied.|
|AuthenticationCredentialsMissing||403 - Forbidden||No Authentication details were found with your request. Please ensure that you are sending your API Access ID and Secret API Access Key (if required) correctly.|
|InternalError||500 - Internal Server Error||We encountered an internal error. Please try again later.|
|InvalidAPIAccessId||403 - Forbidden||The Doculicious API Access ID you provided does not exist in our database.|
|InvalidElementValue||400 - Bad Request||The element value you passed through is invalid.|
|InvalidFilter||400 - Bad Request||A filter you passed to this resource is invalid.|
|InvalidJSON||400 - Bad Request||The JSON you passed through to this resource is invalid.|
|InvalidParameter||400 - Bad Request||A parameter you passed to this resource is invalid.|
|InvalidPropertyValue||400 - Bad Request||The value you passed to this property resource is invalid. Please check the accepted data types for this property.|
|InvalidRepresentationFormat||400 - Bad Request||The representation format requested is invalid for this method. Check that the file-extension you are using is a valid one for this method.|
|InvalidXML||400 - Bad Request||The XML you passed through to this resource is invalid.|
|MethodNotAllowed||405 - Method Not Allowed||That method is not allowed against this resource.|
|NoSuchResource||404 - Not Found||The resource you are trying to reach could not be found.
(Note: This will be returned when filtering a collection causes no resources to be returned, even though the unfiltered collection contains resources.)
|NotAuthorised||403 - Forbidden||You are not authorised to access or interact with the requested resource.|
|NotImplemented||501 - Not Implemented||The resource and method you requested have not yet been implemented.|
|SchemeNotAllowed||403 - Forbidden||That scheme is not allowed against this resource. You must use HTTPS to access this resource.|
|TemplateInactive||400 - Bad Request||The Template you are trying to act on is inactive and cannot be used for this purpose.|
|TemplateSettingsIncorrect||400 - Bad Request||There is a problem with one of the template settings. (Note: More specific information should be provided in each individual error message)|
|UnsafeResourceCall||403 - Forbidden||Requests to HTTP resources MUST not contain an API Secret Key. This should only be sent using HTTPS requests.|