Conventions¶

URL Parameters

Documents

Envelopes

URL Parameters¶

When making a URL request, parameters can be included to control what is returned from the server. Each URL parameter is optional.

URL Parameter	Description
filter	NS Predicate string for filtering results.
count	Limit the number of results that come back from resource.
offset	The start position of results, used for paging result sets. Can be used with ‘count’ parameter.
order_by	‘column:order’ to be used for sorting resource list results. Can have multiple columns and orders seperated by commas. For descending order ‘desc’ and ascending order is ‘asc’.
showall	Show all is a special flag used in some cases to override the default filtering. For example, product listing is usually filtered to only current products. Show all is required to return the full listing.

For example, the following url request will retrieve 50 results starting at result 101 with the order ascending based on the product’s code:

/products/?offset=101&count=50&order_by=code:asc

Warning

For simplicity of implementation, the server currently supports accepting 0 and 1 as valid boolean filters.

Documents¶

When rendering resources, there are conventions we use to describe what is displayed using XML tag attributes.

Attribute Name	Description
id	id of the resource.
uri	uri to fetch the resource.
full_render	true,false for partial display. True means that the resource has all it’s fields displayed when false indicates a partial set of fields are displayed for the resource.
deleted	true, absent. True means the resource has been deleted.
total_count	When total count is present on a list of items, it indicates that cursoring has occurred. If the total number of items returned is less than the total count, it means that more items can be returned by accessed using count and offset parameters.
etag	Current optimistic offline locking version number. This naming convention matches the HTTP naming

Below is an example of a user resource with the attributes mentioned above:

<user uri="https://localhost:9630/users/1002/" id="1002" resource_type="current" full_render="false">
    <username>claire</username>
    <password/>
    <name>
        <first>Claire</first>
        <last>Ambrose</last>
    </name>
    <email/>
    <account_locked>false</account_locked>
    <privilege uri="https://localhost:9630/privileges/0/" id="0" resource_type="current">
        <name>Administrator</name>
    </privilege>
    <internal_user>false</internal_user>
    <active>true</active>
</user>

Envelopes¶

When multiple documents are created/modified/deleted or read (e.g. it’s sometimes convenient to return multiple setup resources on the first request) by a single request , the <response/> envelope is used to indicate multiple items. Example:

<response>
    <pos_settings>...</pos_settings>
    <transaction_invoice>...</transaction_invoice>
</response>

Suggested Improvements and Additions¶

HTTP Methods

There are six supported method types: GET, POST, PUT, DELETE, LOCK, UNLOCK

Method	Description
GET	Gets are used to retrieve both individual documents and list of documents.
POST	Posts are used to create new documents and to trigger “actions” on individual documents.
PUT	Puts are used to update the details on individual documents.
DELETE	Deletes are used to delete an individual document.
LOCK	Lock is used to restrict actions on a particular document (This is a non standard HTTP method). It’s important to note that locks are reference counting.
UNLOCK	Unlock is used to release control of a particular documents.

URI Naming

All resources use names relative to the root. Lists of documents are denoted by having a trailing slash in the uri. List names commonly take the form of a plural noun. Example:

/products/
/product_inventory/
/invoices/

Individual documents are denoted by no trailing slash in the uri and form a unique identifier for the document. Example:

/products/1234
/product_inventory/1234
/scheduled_tasks/iStats

“Actions” on documents are denoted by no trailing slash in the uri. “Action” names usually take the form of a singular noun and belong to an individual document. However, for convenience they may also take the form of a verb. Example:

/product_inventory/1234/adjustment
/product/delete_orphans_photos

Sub resources follow the same conventions. Example:

/invoices/4567/lineitems/9876

Schema Naming

Documents are most often named in a similar fashion as URI representing them. This however is not a requirement as documents can be referenced from multiple uris. Document schema names usually take the form of a singular noun. Example:

<product id="1234" uri="/products/1234">
    ...
</product>

Lists of documents are commonly denoted by using the plural form of the document name. Example:

<products>
    <product id="1234" uri="/products/1234"/>
    <product id="4321" uri="/products/4321"/>
</products>

In rare cases where the plural is not available or appropriate other conventions can be used such as suffixing “_list” to the name of the document. Example:

<product_list>
    <product id="1234" uri="/products/1234"/>
    <product id="4321" uri="/products/4321"/>
</product_list>

Schema Definition

Schemata are defined by placing an example of the schema in Request/Response blocks. In these examples the data values are replaced with their type and expected value, followed by an xml comment describing the field. Example:

<example uri="/example/[integer:>0]" id="[integer:>0]">
    <string_example>[string: max(255)]</string_example><!-- Indicates all string values are acceptable -->
    <int_example>[integer:0-5]</int_example><!-- Indicates simple integer range of 0-5 exclusively -->
    <int_example_two>[integer: 0 | 5-10 | > 14) & < 100]</int_example_two><!-- Using simple Boolean operators to indicate values of 0,5,6,7,8,9,10 or greater 14 but less than 100 -->
    <enum_example>[enum: RUNNING | COMPLETED | SLEEPING]<enum_example><!-- Indicates specific acceptable values -->
    <bool_example>[bool]<bool_example><!-- Must be true of false -->
</example>