Data Import » REST API » Example

REST API example

This is a worked example to implement a REST API to update a project title for a user, given their username.

Control file

Use the data import admin interface to view the haplo:person model:

We want to update the dc:attribute:title of the phd:project Destination.

The admin UI shows a “Depends on profile” tag above the list of Names in the model, so we know that the phd:project depends on the profile being loaded, so the user can be identified. Therefore, we need to load the profile Destination, and then the phd:project dependent Destination is automatically loaded or created.

{
    "dataImportControlFileVersion": 0,
    "model": "haplo:person",
    "files": {
        "DEFAULT": {
            "read": "json",
            "singleRecord": true
        }
    },
    "instructions": [
        {
            "source": "username",
            "destination": "load:by-ref",
            "name": "ref",
            "filters": ["haplo:username-to-ref"]
        },
        {
            "action": "load",
            "destination": "profile",
            "using": "load:by-ref"
        },
        {
            "source": "title",
            "destination": "phd:project",
            "name": "dc:attribute:title"
        }
    ]
}

The three Instructions:

• Look up the username in the API request to find the ref of the user’s profile.
• Load the profile, using this ref.
• Update the title of the project to the title in the API request.

Note the use of singleRecord in the files section, as this API will only be updating one project in a single request.

This control file could be generated through the admin UI:

Select dc:attribute:title in the project, click Generate control file, then modify it:

• Add "singleRecord":true to the DEFAULT file.
• Change the source names to match your input data.

Create the API

Use the admin user interface to create the API:

and fill out the form with:

URL	update-title
Description	Update project title
Enabled	Yes
Response	JSON
Control file	Copy and paste the control file above.

Click New REST API to create the API.

Create an API key

After creating the REST API, click the Create API key… button to create an API key.

This API key is restricted so it can only access this REST API.

Prepare request data

Create a file, request.json, which contains the data:

{
    "username": "jbloggs",
    "title": "Updated title"
}

Adjust the file with a username that is used in your application.

Call the endpoint

The details page for the REST API will give the full endpoint URL. Write a script to call it, inserting the API key and hostname at the top:

#!/bin/sh
set -e

API_KEY=API_KEY_GOES_HERE
FILE_DIRECTORY=.
SERVER=app.example.org

curl -X POST --data-binary @request.json --user haplo:${API_KEY} https://${SERVER}/api/push-data/update-title

This script will POST the contents of the request.json file to the endpoint and update the project title.

View the project record, and verify the project title has been updated.