Data Import » REST API

REST API

The data import framework provides a simple administrative user interface to implement REST style APIs for adding and updating information.

Plugins can also provide default REST API definitions which can be edited by administrators.

To add a REST API, click:

If the menu entries aren’t available, ensure the haplo_data_import_api plugin is installed.

Fill out the form to define the API:

URL	The name to use in the endpoint’s URL.
Description	A short description of the API.
Enabled	Whether the API is enabled. This option is primarily so redundant APIs can be turned off.
Response	Use JSON or XML for the response.
Control file	See below for how control files are used to describe the API.

Everything apart from the URL can be edited later.

Control files for REST APIs

The REST APIs run a Batch import with the request body as the input file. Typically these request bodies will just update one record.

Write a control file in the normal way, noting:

• In the files section, use the name DEFAULT.

• Choose either JSON or XML format. As your API will probably be intended to update just a single record, you might want to use the singleRecord:true option to make the requests shorter.

See the example definition for a simple control file.

Using the API

After creating the API, the admin interface will show you the full URL of the endpoint, which will look something like:

https://app.example.org/api/push-data/api-name

Creating an API key

Requests should be POSTed to this URL using an API key, which you can generate by clicking the Create API key… button on the REST API’s page. It’s important to create keys using this user interface so they are restricted to just accessing a single REST API.

Once created, API keys are managed in System management:

Scroll to the bottom to view the API keys.

POST data to the REST API

Once you have the API key, POST the data in the specified format to the endpoint, using HTTP basic authentication with the username haplo and the API key as the password.

See the example definition for a worked example and script.

Response

The response is in JSON or XML, with a 200 status code if everything succeeded. The responses are formatted in JSON as:

{
    "result": "failure",
    "applied": 1,
    "failures": 1,
    "errorCount": 1,
    "errors": [
        "Example error"
    ],
    "actions": [
        {
            "record": "record 1",
            "changed": [
                {
                    "kind": "object:save",
                    "destination": "example",
                    "ref": "80qqq",
                    "new": false
                }
            ]
        }
    ]
}

or in XML as:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response applied="1" errorCount="1" failures="1" result="failure">
  <errors>
    <error>Example error</error>
  </errors>
  <actions>
    <record identifier="record 1">
        <changed kind="object:save" destination="example" ref="80qqq" new="false"/>
    </record>
  </action>
</response>

The JSON properties or XML attributes/child nodes are:

result	The overall result of the API request, success when everything worked without errors, failure if some data couldn’t be imported, or error if there was an exception.
applied	The number of records successfully applied.
failures	The number of records which couldn’t be applied.
errorCount	The number of errors.
errors	Zero or more error messages.
actions	Zero or more records, corresponding to actions taken. Each will include a record identifier (record), and a number of changed elements. These contain kind, the kind of action that happened, destination, the destination the action happened to, and any other information specific to the kind, such as relevant identifiers. See below for information on specific kinds.

Because the APIs can receive multiple records in a single call, a result may be a partial success. You are recommended to just send a single record.

Actions

The possible kinds of actions, and the extra information they include in the response, are listed below:

object:save

This action kind records that the destination specified in destination represents a StoreObject which has been modified and saved.

Field	Meaning
ref	A string representing the Ref of the object that was saved
new	Boolean. Whether this action created this object.