Resource Data

All API calls will return some type of data, either a representation of the requested resource or an error if something went wrong. This page lists all of the resources that can currently be returned, beginning with some general information about resources and what may be found within them.

Basic Resources
Links within resources
The difference between UIDs and IDs
Resources

Basic resources

Some resources below are flagged as being "Basic". This means that not all the properties for that resource will be populated, and is usually the case with sub-resources, ones that are a part of another resource. If you need the full resource, you should retrieve it using the basic resources "self" link relation.

Links within resources

Doculicious resources may have links within them. These links are for describing different actions that you can take for the resource you requested, or on related resources. All links support the following attributes:

Name	Description
rel	Actions that are related to this resource are specified by the following values. The appropriate HTTP method must be used when calling the linked resources. self - GET the full representation of this resource using the links href. next - GET the next page of data for this collection resource using the links href. previous - GET the previous page of data for this collection resource using the links href. parent - GET the parent of this resource using the links href. edit - Edit the resource using a PUT to the links href. add - Add a new resource using a POST to the links href. delete - Remove this resource using a DELETE to the links href. thumb - Only in Images. GET the thumbnail image file of this image. img - Only in images. GET the full-sized image file of this image.
href	The URI of a resource.
title	Optional. A friendly description of the resource linked to.

Name

Description

rel

Actions that are related to this resource are specified by the following values. The appropriate HTTP method must be used when calling the linked resources.

self - GET the full representation of this resource using the links href.
next - GET the next page of data for this collection resource using the links href.
previous - GET the previous page of data for this collection resource using the links href.
parent - GET the parent of this resource using the links href.
edit - Edit the resource using a PUT to the links href.
add - Add a new resource using a POST to the links href.
delete - Remove this resource using a DELETE to the links href.
thumb - Only in Images. GET the thumbnail image file of this image.
img - Only in images. GET the full-sized image file of this image.

href

The URI of a resource.

title

Optional. A friendly description of the resource linked to.

If a link appears in a resource then the action and resource they represent will be available for use. All addressable resources will have a _self link. If an extension was specified for the representation os a resource, all links will use the same.

Hiding Links

You can hide links in resources by passing the _hideLinks=true parameter to the resource in the query string. This can be used to reduce the size of responses, especially for large collections where each resource contains multiple links, and you don't plan on using them.

Link Examples

Links can appear in XML and JSON responses. Below are examples of how they might appear in a collection resource:

XML

<?xml version="1.0" encoding="UTF-8"?>
<elements>
    <uid>https://api.doculicious.com/templates/1234abcd5678ef90/elements</uid>
    <link rel="self" href="https://api.doculicious.com/templates/1234abcd5678ef90/elements?readOnly=false&amp;_rows=3&amp;_page=3"/>
    <link rel="previous" href="https://api.doculicious.com/templates/1234abcd5678ef90/elements?readOnly=false&amp;_rows=3&amp;_page=2"/>
    <link rel="next" href="https://api.doculicious.com/templates/1234abcd5678ef90/elements?readOnly=false&amp;_rows=3&amp;_page=4"/>
    <page>3</page>
    <rows>3</rows>
    <totalRows>22</totalRows>
    <resources>
        <element>...</element>
        <element>...</element>
        <element>...</element>
    </resources>
</elements>

JSON

{
    "uid": "https://api.doculicious.dev/templates/9940be508f09a3ac/elements",
    "link": 
    {
        "@rel": "self",
        "@href": "https://api.doculicious.dev/templates/9940be508f09a3ac/elements.json?readOnly=false&_rows=3&_page=3"
    },
    "link": 
    {
        "@rel": "previous",
        "@href": "https://api.doculicious.dev/templates/9940be508f09a3ac/elements.json?readOnly=false&_rows=3&_page=2"
    },
    "link": 
    {
        "@rel": "next",
        "@href": "https://api.doculicious.dev/templates/9940be508f09a3ac/elements.json?readOnly=false&_rows=3&_page=4"
    },
    "page": 3,
    "rows": 3,
    "totalRows": 22,
    "resources": 
    [
        {...},
        {...},
        {...}
    ]
}

Top of page

The difference between UIDs and IDs

Some resources have both a UID and an ID. A UID is a globally unique identifier for a resource, in the form of a URI which is addressable over the internet. An ID is a string that identifies some type of entity within Doculicious - but this entity may not be unique, is usually associated with some type of parent, and cannot be addressed over the Internet without knowing who that parent is. Here's an example:

When you add a Text Box Element to a template you are creating, that element is assigned an ID which will be unique within that particular template. However, when a new entry is made for that template (when someone fills in and completes your form), the new entry will have an instance of all the elements from the parent template. The values stored in the element may be different, say when someone fills in their address in that Text Box Element, but the element will have the same ID in the template and all the entries. The UID of this element depends on which instance we are trying to reference. The UID for this element within its template would be something like http://api.doculicious.com/templates/{The Templates ID}/elements/{The Elements ID}. The UID for the element in a particular entry would be something like: http://api.doculicious.com/entries/{The Templates ID}/elements/{The Elements ID}

Resources

A resource is made up of a number of properties that contain values such as text, numbers, other resources or collections of resources. Some of these properties are optional and may not be returned by the server. Optional properties will be flagged in the table below as "Optional". The following tables and code examples outline the current resources that can be returned using the Doculicious API.

Collection Resources

A Collection Resources is a resource that contains multiple other resources of some type. Some Collection resources can be filtered using fields of the resource that it holds. These filters will be documented for each resource that returns a collection, or has a sub-collection within it. Because of this filtering, Collection Resources might only contain a subset of the total number of resources available. This enables paging through a collections data, and lets you manage the request size. Collection Resources therefore contain information about the requested rows and the actual rows returned. All returned resources will be available within the "resources" field.

Name	Description	Type
uid	The globally unique ID of the unfiltered collection resource.	String
currentPage	The current page of data this collection contains	Integer
requestedRows	The amount of rows requested for each page	Integer
returnedRows	The amount of rows actually returned for this page	Integer
totalRows	The total amount of rows this query would return without paging	Integer
resources	The resources returned within this collection.	[resource, ...]

XML

<?xml version="1.0" encoding="UTF-8"?>
<entries>
    <uid>http://api.doculicious.come/entries/1234abcd5678ef90</uid>
    <currentPage>2</currentPage>
    <requestedRows>3</requestedRows>
    <returnedRows>3</returnedRows>
    <totalRows>71</totalRows>
    <resources>
        <entry>...</entry>
        <entry>...</entry>
        <entry>...</entry>
    </resources>
</entries>

JSON

{
    "uid": "http://api.doculicious.come/entries/1234abcd5678ef90",
    "currentPage": 2,
    "requestedRows": 3,
    "returnedRows": 3,
    "totalRows": 71,
    "resources": 
      [
        {...},
        {...},
        {...}
      ]
}

Top of page

Entry resource

Information about a particular entry. The [data] collection of this resource may be empty if only the metadata of the entry has been requested.

Name	Description	Type
uid	The globally unique ID of this entry	String
id	The ID of this entry.	String
adminComments	Optional. A comment made to this entry after submission.	String
createdDate	The date and time this entry was made	Timestamp
processed	Has this entry been flagged as processed?	Boolean
deleted	Has this entries data been deleted?	Boolean
modifiedDate	The date this resource was last modified	Timestamp
modifiedBy	The user who last modified the resource	<user (basic)>
ipAddress	The IPAddress used to make this entry	String
template	The template this entry was made for	<template (basic)>
custom1	Optional. A custom value you can set each time your template is displayed. Read more here -> About Custom values	String
custom2	Optional. A custom value you can set each time your template is displayed. Read more here -> About Custom values	String
elements	The data of this entry as a collection of element resources	[<element (basic)>, ...]

XML

<?xml version="1.0" encoding="UTF-8"?>
<entry>
    <uid>https://api.doculicious.dev/entries/1234abcd5678ef90/1234abcd5678ef90</uid>
    <id>1234abcd5678ef90</uri>
    <createdDate>2009-04-23T15:34:23+04:00</createdDate>
    <processed>false</processed>
    <deleted>false</deleted>
    <modifiedDate>2009-04-28T15:14:23+04:00</modifiedDate>
    <modifiedByUser>
        <uid>1234abcd5678ef90</uid>
        <name>A Username</name>
    </modifiedByUser>
    <ipAddress>127.0.1.1</ipAddress>
    <template>
        <uid>1234abcd5678ef90</uid>
        <name>The Templates Name</name>
    </template>
    <custom1>45</custom1>
    <elements>    
        <uid>https://api.doculicious.dev/entries/1234abcd5678ef90/1234abcd5678ef90/elements</uid>
        <currentPage>2</currentPage>
        <requestedRows>3</requestedRows>
        <returnedRows>3</returnedRows>
        <totalRows>71</totalRows>
        <resources>    
            <element objectType="basic">...</element>
            <element objectType="basic">...</element>
            <element objectType="basic">...</element>
        <resources>
    </elements>
</entry>

JSON

{
    "uid": "https://api.doculicious.dev/entries/1234abcd5678ef90/1234abcd5678ef90",
    "id": "1234abcd5678ef90",
    "createdDate": "2009-04-23T15:34:23+04:00",
    "processed": false,
    "deleted": false,
    "modifiedDate": "2009-04-28T15:14:23+04:00",
    "modifiedByUser": 
        {
            "uid": "1234abcd5678ef90",
            "name": "A Username"
        },
    "ipAddress": "127.0.1.1",
    "template": 
        {
            "uid": "1234abcd5678ef90",
            "name": "The Templates Name"
        },
    "custom1":45,
    "elements":
        {
            "uid":https://api.doculicious.dev/entries/1234abcd5678ef90/1234abcd5678ef90/elements,
            "currentPage":2,
            "requestedRows":3,
            "returnedRows":3,
            "totalRows":71,
            "resources":
                [
                    {element ...},
                    {element ...},
                    {element ...}
                ]
            resources>
        {
}

Top of page

Template resources

Templates can be returned in multiple ways by resources. Currently we only return a basic template representation which contains a minimal amount of information, but enough for the current resources available. In the future we will add more information to this resource, and compatibility with the POST method.

template (basic)

Name	Description	Type
id	The ID of this template	String
name	The name of this template	String

XML

<?xml version="1.0" encoding="UTF-8"?>

<template>
    <id>1234abcd5678ef90</id>
    <name>The Templates Name</name>
</template>

JSON

{
    "id": "1234abcd5678ef90",
    "name": "The Templates Name"
}

Top of page

User resources

Users resources represent the creators, owners and modifiers of Doculicious resources. Currently we only provide minimal information about users.

user (basic)

Name	Description	Type
id	The ID of this user	String
name	The name of this user	String

XML

<?xml version="1.0" encoding="UTF-8"?>
<user>
    <id>1234abcd5678ef90</id>
    <name>A Username</name>
</user>

JSON

{
    "id": "1234abcd5678ef90",
    "name": "A Username"
}

Top of page

Image resources

Images are the values of ImageBox elements and contain information about the image such as the ID and path to the actual image file.

Image (basic)

A basic image contains the ID of the image in the Doculicious system. It will also contain

Name	Description	Type
id	The ID of this image	String
link rel="thumb"	A link to the thumbnail image file for this image	Link
link rel="img"	A link to the full image file for this image	Link

XML

<?xml version="1.0" encoding="UTF-8"?>
<image>
    <id>1234abcd5678ef90</id>
    <link rel="thumb" href="http://doculicious.dev/img/9/1234abcd5678ef90_t.png"/>
    <link rel="img" href="http://doculicious.dev/img/9/1234abcd5678ef90_f.png"/>
</image>

JSON

{
    "id": "1234abcd5678ef90",
    "link": 
    {
        "@rel": "thumb",
        "@href": "http://doculicious.dev/img/9/1234abcd5678ef90_t.png"
    },
    "link": 
    {
        "@rel": "img",
        "@href": "http://doculicious.dev/img/9/1234abcd5678ef90_f.png"
    }
}

Top of page

Page resources

Entries and Templates all have atleast one page, upon which its elements are placed. A page has an ID, and each element will have a reference to the page it is on.

Page (basic)

A basic page contains the ID of the page in the Doculicious system, and also its page number:

Name	Description	Type
id	The ID of this page	String
number	The Page Number of this page	Integer

XML

<?xml version="1.0" encoding="UTF-8"?>
<image>
    <id>1234abcd5678ef90</id>
    <page>1</page>
</image>

JSON

{
    "id": "1234abcd5678ef90",
    "page": "1"
}

Top of page

Element resource

Elements are the content of templates, entries and styles. Each element has properties which define how it looks, where it is placed on a template, and what value it should display.

element (basic)

A basic element contains a small subset of a full elements values, just enough to identify it and retrieve it's value.

Name	Description	Type
uid	A globally unique identifier for this particular element instance. The format is of a URI that includes the ID of the template or entry the element occurs within, and the ID of the element itself.	String
id	The ID of this element. Elements are unique to a single template, but occur in every entry made from that template. This ID is used to populate elements when using HTML POSTed forms.	String
name	The name given to this resource	String
type	What type of element it is - Text, Image, Checkbox etc	String
page	The page of the template this element appears on	Page
tabIndex	The order it appears on the page	Integer
multiLine	Is it a multi-line text field?	Boolean
value	The submitted or default value. Will contain an attribute that describes the type of data - String, Boolean or Image	String or Boolean or Image
readOnly	Is the field read only?	Boolean

* If the element is being

XML

<?xml version="1.0" encoding="UTF-8"?>
<element>
    <uid>https://api.doculicious.dev/templates/9940be508f09a3ac/elements/1234abcd5678ef90</uid>
    <id>1234abcd5678ef90</id>
    <name>element_2</name>
    <type>TextBoxElement</type>
    <page>1</page>
    <tabIndex>2</tabIndex>
    <multiLine>false</multiLine>
    <value class="string">The Value</value>
    <readOnly>false</readOnly>
</element>

JSON

{
    "uid": "https://api.doculicious.dev/templates/9940be508f09a3ac/elements/1234abcd5678ef90"
    "id": "1234abcd5678ef90",
    "name": "element_2",
    "type": "TextBoxElement",
    "page": 1,
    "tabIndex": 2,
    "multiLine": false,
    "value": {
              "@class": "string",
              "$": "The Value"
            },
    "readOnly": false
}

Top of page

Bookmark/Search this post with

Help

Table of contents

Basic resources

Links within resources

Hiding Links

Link Examples

XML

JSON

The difference between UIDs and IDs

Resources

Collection Resources

XML

JSON

Entry resource

XML

JSON

Template resources

template (basic)

XML

JSON

User resources

user (basic)

XML

JSON

Image resources

Image (basic)

XML

JSON

Page resources

Page (basic)

XML

JSON

Element resource

element (basic)

XML

JSON