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’sprofile
. - 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 theDEFAULT
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.