OneIS API Documentation

This document describes how to use the API to access and modify data in OneIS.

Authentication

Before the API can be used, an API key must be generated to authenticate each request. An API key is a random string of characters, and is equivalent to the user and password. The access granted is identical to the access for the user.

To generate a key, log into OneIS as an administrator. Click Tools then System Management. Click Users then the name of the user you wish to authenticate as. Scroll down, and click New API key. Create the key, then click Reveal this API key to show the key.

NOTE: The API key generated by these instructions is only valid for URLs beginning /api.

The API key is sent in requests by, in order of checking:

[1] The _ak request parameter cannot be used with a file upload multipart/form-data request because the authentication takes place before the request body is parsed.

[2] The _ak parameter cannot be used in the query part of a GET request. Use POST requests when passing the API key as a request parameter.

API Style

The API is an “XML REST”-like API accessed via HTTPS (or HTTP if the system is configured without SSL). It does not fully follow the REST principle, and the XML currently has no DTD or XML schema.

The endpoints are all relative to the system base URL. The hostname is used by the server to identify the customer’s system. For example, if the system URL used by the users is http://example.infomanaged.co.uk then given the endpoint /api/example the URL http://example.infomanaged.co.uk/api/example should be requested.

Notation

In documentation of the XML format, the hierarchy follows the hierarchy of the XML. monospace is used to represent the elements, with the suffic * meaning zero or more, + meaning 1 or more, ? means 0 or 1, no suffix means always 1. italics show the attributes on the parent element. TEXT represents the text node contained in the elemement. For example:

Principles

Objects

Objects are ordered lists of (descriptor, qualifier, value) triples. The descriptor and qualifier say what the value means, eg “Title, Alternative”, to implement qualified Dublin Core meta data schemes. The value is a bit of data, of various types including text, datetime, numbers and identifiers (phone number, ISBN, URL, etc) and most importantly, object reference, acting as a link to other objects.

Objects are stored in sections, used to divide up the objects into groups in a user defined manner. Object references are formed of the section number plus an id within that section. Section 1 is special, used to contain the default schema.

Everything is defined in terms of objects, eg descriptors themselves are object references to a schema object describing the descriptor.

The object store places no restrictions on the data, but uses the following if they are present:

Any of these fields can be changed at any time without restriction, and this is used by the application.

Object references

Object references (objrefs) look like 1-206w. It is formed of two hexadecimal numbers, with the transformation tr/abcdef/qvwxyz/ applied to remove the possibility of spelling words in object URLs.

The first number is the section ID, the second is the object ID within the section.

Objects in section 1 always have the same meaning, that is, refer to the same type, attribute or qualifier definition. Note that these definitions may have been customised by the user, and may not necessarily exist in all systems depending on which template was used to initialise the system. Given this, it is acceptable to use the objrefs as constants within your code, as long as their existence within the schema is checked.

Since attributes, qualifiers and types are all defined by objects, objrefs are used to describe them in the XML.

Schema

Endpoint: /api/schema/data_model

Each system has its own schema. There is a common schema, which is usually present, but the administrators of that system may have augmented it.

The returned schema has the format:

Aliased attributes

Aliased attributes are included in the schema “for information only”. They are used by the OneIS user interface to rename other attributes when their meaning in a particular context is inappropriate, or where another data type is more useful.

A good example of the use of aliased attributes is in the default Person type. OneIS uses taxonomies in the Subject attribute to classify all objects consistently. However, people don’t have a subject, so the Subject attribute is aliased to Expertise. In addition, the Title field is aliased to Name and set to the Person’s name data type. While every object must have a title for display in search results and links, Title means something different when referring to people, and the person’s name data type is much better for writing names than a simple text field.

Aliased attributes are applied in the user interface only. Stored objects use the underlying attributes, and when writing objects using this API, aliased attributes cannot be used.

Data types

Type labels

Example

<?xml version="1.0" encoding="UTF-8"?>
<schema>
  <qualifiers>
    <qualifier name="alternative" ref="1-3y8">
      <display_name>Alternative</display_name>
    </qualifier>
    ...
  </qualifiers>
  <attributes>
    <attribute vtype="0" name="type" ref="1-x2">
      <display_name>Type</display_name>
      <allowed_qualifiers>
        <null_qualifier/>
      </allowed_qualifiers>
    </attribute>
    <attribute vtype="16" name="title" ref="1-x3">
      <display_name>Title</display_name>
      <allowed_qualifiers>
        <null_qualifier/>
        <qualifier ref="1-3y8"/>
      </allowed_qualifiers>
    </attribute>
    ...
  </attributes>
  <aliased_attributes>
    <aliased_attribute alias_of="1-9w4" name="review" ref="1-325">
      <display_name>Review</display_name>
    </aliased_attribute>
    ...
  </aliased_attributes>
  <types>
    <type name="event" root_type="1-209y" ref="1-209y">
      <display_name>Event</display_name>
      <attributes>
        <attribute ref="1-x3"/>
        <attribute ref="1-x9"/>
        <attribute ref="1-x2"/>
        <attribute ref="1-25y"/>
        <attribute ref="1-263"/>
        <attribute ref="1-190"/>
        <attribute ref="1-262"/>
        <attribute ref="1-25q"/>
        <attribute ref="1-9w5"/>
        <attribute ref="1-325"/>
        <attribute ref="1-9w6"/>
        <attribute ref="1-x5"/>
      </attributes>
      <create_allowed_sections>
        <section default="true" sec_id="9"/>
      </create_allowed_sections>
    </type>
    <type parent="1-209y" name="networking" root_type="1-209y" ref="1-20q0">
      <display_name>Networking</display_name>
    </type>
    ...
  </types>
</schema>

Section info

Endpoint: /api/schema/sections

Returns an XML document:

Example

<?xml version="1.0" encoding="UTF-8"?>
<sections>
  <section name="classify" sec_id="3">
    <display_name>Classification</display_name>
    <permissions uid="20">
      <permission name="read"/>
      <permission name="approve"/>
      <permission name="create"/>
      <permission name="update"/>
      <permission name="search"/>
      <permission name="delete"/>
      <permission name="navigate"/>
      <permission name="collaborate"/>
    </permissions>
  </section>
  ...
</sections>

Accounting information and limits

Endpoint: /api/edit/limits

Returns an XML document:

Note that the values returned may overflow a 32 bit integer.

Usage values may be zero if accounting data is not available. In this case, uploads and object creation will be allowed.

Object XML representation

Used in various APIs.

Note that aliased attributes cannot be used in objects; they are for display and editing only.

Value data representation

The values marked with X above depend on the data type. If vt < 16 (non-text type) the value is converted to text and output as a text node. There are some exceptions, documented below.

Text-like values are output as:

Note: currently the UI doesn’t support multi-lingual text, so only the first text string is used.

Identifier values just output a single text element with no lang or default attributes.

Newline characters follow the UNIX conventions, with a single \n character.

Text types

There are various text formats, which are rendered to HTML differently.

Text (16)

Single line of text, rendered as is with HTML encoding. No newline characters should be included.

Paragraph text (24)

Single newline characters are turned into <br> HTML elements. Multiple newline characters indicate paragraph breaks.

Multiline text (33)

One or more newline characters are turned into <br> HTML elements.

Document text (25)

The TEXT value in the XML representation contains a serialised XML document fragment, XML encoded. XML parsers should return it as a string suitable for XML parsing itself.

When parsed, it returns a tree representing rich text with inserted widgets.

The supported types and values of widgets are:

Datetime

Encoded in ISO 8601 format as YYYY-MM-DDThh:mm:ssTZD as the TEXT child of the a element.

Telephone numbers

The above format is strict, and requires correct country codes for OneIS to handle the data correctly. However, data is not always available in this form. When reading XML, OneIS also supports this form:

Data will be converted on reading to a best guess for the country code and local number. guess_country should be set to the country the data originated from. For example, even if the number is a US number, you should set guess_country to GB if the data was collected in England.

If you find any inputs which give bad results, please send them to OneIS Support so we can improve the guessing algorithm.

Postal addresses

NOTE: The country field must be a valid ISO code. If any other data is sent, for example, the country name as text, the server will reject the object.

URL

Person’s name

File reference

File references are deliberately non-guessable for security reasons. Obtain file references by uploading new files (see below) or copying from an existing object.

The system supports referring to the same file from two different objects, but this is not encouraged as it may lead to user confusion.

Example

<object ref="6-6" 
        created_user="20" updated="2008-10-30T14:38:33+00:00" 
        updated_user="20" created="2008-10-30T14:38:33+00:00">
  <attributes>
    <a d="1-x3" vt="35">
      <person_name culture="western">
        <last>Bloggs</last>
        <first>Joe</first>
      </person_name>
    </a>
    <a d="1-x2" vt="0">1-20x1</a>
    <a d="1-259" vt="0">6-5</a>
    <a d="1-193" vt="16">
      <text default="true" lang="en">Developer</text>
    </a>
    <a d="1-191" vt="29">
      <text>joe@example.com</text>
    </a>
    <a d="1-195" vt="32">
      <telephone_number>
        <country>GB</country>
        <number>020 1234 5678</number>
        <intl_form>+44 20 1234 5678</intl_form>
      </telephone_number>
    </a>
    <a d="1-195" q="1-76x" vt="32">
      <telephone_number>
        <country>GB</country>
        <number>07777 123 456</number>
        <intl_form>+44 7777 123456</intl_form>
      </telephone_number>
    </a>
    <a d="1-194" vt="36">
      <postal_address>
        <street1>1 High Street</street1>
        <city>Some City</city>
        <county>Anywhere</county>
        <postcode>XX1 2YY</postcode>
        <country>GB</country>
      </postal_address>
    </a>
    <a d="1-x5" vt="0">3-3v</a>
    <a d="1-25v" vt="0">q-3000</a>
    <a d="1-9w5" vt="24">
      <text default="true" lang="en">Some example text.
Includes line breaks.</text>
    </a>
    <a d="1-190" vt="30">
      <url>http://www.example.com</url>
    </a>
  </attributes>
</object>

Get object

Endpoint: /api/object/ref/<objref> (where <objref> is an object reference)

Returns

Use batch or search requests to retrieve multiple objects, if possible.

Example

<?xml version="1.0" encoding="UTF-8"?>
<response status="success">
  <read url="http://dev/contact/6-6/joe-bloggs" ref="6-6">
    <object>
      ...
    </object>
  </read>
</response>

Batch operation (create, read, update, delete)

Endpoint: /api/object/batch

POST an XML document to the endpoint with the Content-Type header set to text/xml; charset=utf-8. This has the format:

The document must include the <?xml version="1.0" encoding="UTF-8"?> declaration.

A batch may contain up to 64 operations. A request containing more will be rejected by the server, with no operations performed.

Operations can be in any order, and are executed in that order.

Response is:

Each operation in the request has a corresponding create, read, update, delete or error element, in the same order as the operations in the request.

NOTE: Check the account is sufficiently under the objects limit before creating large numbers of objects.

If the object limit is exceeded and the batch includes a create operation, the entire batch will be rejected with an error response. None of the operations will be executed.

File upload

Endpoint: /api/file/upload_new_file

Endpoint: /api/file/upload_new_file/with_deflate

POST a multipart/form-data encoded request to the endpoint, with parameters:

If the endpoint with the with_deflate suffix is used, then the file must be compressed with the zlib deflate algorithm. The hash and size are for the file before compression.

Response is:

Copy the file_reference values into an object to make the file available for use by the user. If it is not added to an object, the file will be inaccessible.

NOTE: Check the account is sufficiently under the storage limit before uploading large numbers of files.

NOTE: The current version of the API does not allow uploading new versions of existing files. This will be made available in an update.

Searching

Endpoint: /api/search/q

POST or GET this endpoint with parameters:

The search specification parameters are the same as used by the search UI. For experimentation, use the web app to try out searches, then copy the parameters.

See the in-app help text for the search query language. In addition, the following clauses are supported:

Also, flags are supported to modify how the query is run:

Response is:

The number of results returned by the server is not specified, and may vary over queries. Callers should not make assumptions.

Only ask for attributes you’re going to use.