API

General Notes

Arches allows any parameters to be passed in via custom HTTP headers OR via the querystring. All requests to secure services require users to pass a “Bearer” token in the authentication header

To use a an HTTP header to pass in a parameter use the form:

HTTP-X-ARCHES-{upper case parameter name}.

So, for example, these are equivelent requests

curl -H "X-ARCHES-FORMAT: json-ld" http://localhost:8000/surveys

curl http://localhost:8000/surveys?format=json-ld

If both a custom header and querystring with the same name are provided, then the querystring parameter takes precedence.

In the following example “html” will be used as the value for the “format” parameter.

curl -H "X-ARCHES-FORMAT: json-ld" http://localhost:8000/surveys?format=html

Note

Querystring parameters are case sensitive. Behind the scenes, custom header parameters are converted to lower case querystring parameters.

In the following example there are 3 different parameters (“format”, “FORMAT”, and “Format”) with 3 different values (“html”, “json”, and “xml”) respectively

http://localhost:8000/surveys?format=html&FORMAT=json&Format=xml

Authentication

Most Arches API endpoints require an OAuth access token.

OAuth 2.0 is a simple and secure authentication mechanism. It allows applications to acquire an access token for Arches via a quick redirect to the Arches site. Once an application has an access token, it can access a user’s resources on Arches. Authentication with OAuth can be accomplished in the following steps:

Registering an application with Arches

To create an OAuth client for testing go to the url below and create a application using the image below as an example. Then use the client id when generating a OAuth token.

http://localhost:8000/o/applications/

POST /o/token

gets an OAuth token given a username, password, and client id

Note

You should only make this call once and store the returned token securely. You should not make this call per request or at any other high-frequency interval.

This token is to be used with clients registered with the “Resource Owner Password Credentials Grant” type see Registering an application with Arches for more information on registering an application

For additional information see https://tools.ietf.org/html/rfc6749#section-4.3

Form Parameters:  

• username – a users username (or email)
• password – a users password
• grant_type – “password”
• client_id – the registered applications client id, see Registering an application with Arches

Status Codes:

• 401 Unauthorized – there’s no user or the user has been deactivated, or the client id is invalid

Example request:

curl -X POST http://localhost:8000/o/token/ -d "username=admin&password=admin&grant_type=password&client_id=onFiQSbPfgZpsUcl2fBvaaEHA58MKHavl3iuSaRf"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "TS3pE2bEXRCAkRls4IGKCVVa0Zv6FE",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "y3rzXKf8dXdb25ayMMVIligTkqEKr0",
    "scope": "read write"
}

returned when an invalid username or password is supplied

HTTP/1.1 401 Unauthorized
Content-Type: application/json


{"error_description": "Invalid credentials given.", "error": "invalid_grant"}

returned when an invalid client id is supplied, or the registerd client is not “public” or the grant type used to register the client isn’t “Resource Owner Password Credentials Grant”

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "invalid_client"}

Resources

GET /resources/

gets a paged list of resource instance ids in json-ld format

Query Parameters:  

• page – number specifing the page of results to return

Example request:

curl -X GET http://localhost:8000/resources/

curl -X GET http://localhost:8000/resources/?page=2

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "@context": "https://www.w3.org/ns/ldp/",
    "@id": "",
    "@type": "ldp:BasicContainer",
    "ldp:contains": [
        "http://localhost:8000/resources/00000000-0000-0000-0000-000000000100",
        "http://localhost:8000/resources/00000000-0000-0000-0000-000000000101",
        "http://localhost:8000/resources/000ee2fe-4568-457b-960c-3e1ec3f53e10",
        "http://localhost:8000/resources/000fa53f-0f06-4648-a960-c42b8accd235",
        "http://localhost:8000/resources/00131129-7451-435d-aab9-33eb9031e6d1",
        "http://localhost:8000/resources/001b6c4b-f906-4df2-9fcd-b9fda95eed95",
        "http://localhost:8000/resources/0032990e-f8d6-4a7b-8032-d90d3c764b40",
        "http://localhost:8000/resources/003619ca-5fa7-4e75-b3b7-a62f40fe9419",
        "http://localhost:8000/resources/00366caa-3c00-4909-851d-0d650e62f820",
        "http://localhost:8000/resources/003874d7-8e73-4323-bddf-b893651e22c1",
        "http://localhost:8000/resources/003e56a0-d0eb-485f-b975-61faf2f22755",
        "http://localhost:8000/resources/0043a0be-c7be-4a35-9f6c-0ba80269caf4",
        "http://localhost:8000/resources/0060f35d-47a7-4f22-aaf3-fa2d0bd493f7",
        "http://localhost:8000/resources/0069dad8-41b6-4cad-8e54-f72fe8093550",
        "http://localhost:8000/resources/0069db14-a0c1-470e-abf7-eda7b56bf012"
    ]
}

GET /resources/{uuid:resouce instance id}

gets a single resource instance

Query Parameters:  

• format – {“xml”, “json”, “json-ld”}
• indent – number of spaces to indent json output

Request Headers:  

• Authorization – OAuth token for user authentication, see /o/token
• Accept – optional alternative to “format”, {“application/xml”, “application/json”, “application/ld+json”}

Example request:

curl -H "Authorization: Bearer {token}" -X GET http://localhost:8000/resources/{resource instance id}

curl -H "Authorization: Bearer zo41Q1IMgAW30xOroiCUxjv3yci8Os" -X GET http://localhost:8000/resources/00131129-7451-435d-aab9-33eb9031e6d1?format=json&indent=4

Example json response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "business_data": {
        "resources": [
            {
                "tiles": [
                    {
                        "data": {
                            "e4b37f8a-343a-11e8-ab89-dca90488358a": "203 Boultham Park Road"
                            "e4b4b7f5-343a-11e8-a681-dca90488358a": null,
                        },
                        "provisionaledits": null,
                        "parenttile_id": null,
                        "nodegroup_id": "e4b37f8a-343a-11e8-ab89-dca90488358a",
                        "sortorder": 0,
                        "resourceinstance_id": "99131129-7451-435d-aab9-33eb9031e6d1",
                        "tileid": "b72225a9-4e3d-47ee-8d94-52316469bc3f"
                    },
                    {
                        "data": {
                            "e4b3f15c-343a-11e8-a26b-dca90488358a": null,
                            "e4b4ca3d-343a-11e8-ab73-dca90488358a": {
                                "type": "FeatureCollection",
                                "features": [
                                    {
                                        "geometry": {
                                            "type": "Point",
                                            "coordinates": [
                                                -0.559288403624841,
                                                53.2132233001817
                                            ]
                                        },
                                        "type": "Feature",
                                        "id": "c036e50a-4959-4b6f-93d0-2c03068c0948",
                                        "properties": {}
                                    }
                                ]
                            }
                        },
                        "provisionaledits": null,
                        "parenttile_id": "4e40e6f3-8252-4439-831d-c371655cc4eb",
                        "nodegroup_id": "e4b3f15c-343a-11e8-a26b-dca90488358a",
                        "sortorder": 0,
                        "resourceinstance_id": "99131129-7451-435d-aab9-33eb9031e6d1",
                        "tileid": "65199340-32c3-4936-a09e-7c5143552d15"
                    },
                    {
                        "data": {
                            "e4b386eb-343a-11e8-82ef-dca90488358a": "Detached house built by A B Sindell"
                        },
                        "provisionaledits": null,
                        "parenttile_id": "8870d2d6-e179-4321-a8bb-543fd2db63c6",
                        "nodegroup_id": "e4b386eb-343a-11e8-82ef-dca90488358a",
                        "sortorder": 0,
                        "resourceinstance_id": "99131129-7451-435d-aab9-33eb9031e6d1",
                        "tileid": "04bb7bef-1e6e-4228-bd87-3f0a129514a8"
                    }
                ],
                "resourceinstance": {
                    "graph_id": "e4b3562b-343a-11e8-b509-dca90488358a",
                    "resourceinstanceid": "99131129-7451-435d-aab9-33eb9031e6d1",
                    "legacyid": "99131129-7451-435d-aab9-33eb9031e6d1"
                }
            }
        ]
    }
}

PUT /resources/{uuid:resouce instance id}

updates a single resource instance

Query Parameters:  

• format – {“xml”, “json”, “json-ld”}
• indent – number of spaces to indent json output

Request Headers:  

• Authorization – OAuth token for user authentication, see /o/token
• Accept – optional alternative to “format”, {“application/xml”, “application/json”, “application/ld+json”}

Example request:

curl -H "Authorization: Bearer {token}" -X PUT -d {data in json-ld format} http://localhost:8000/resources/{resource instance id}

curl -H "Authorization: Bearer zo41Q1IMgAW30xOroiCUxjv3yci8Os" -X PUT \
-d '{
    "@id": "http://localhost:8000/resource/47a1830c-74ec-11e8-bff6-14109fd34195",
    "@type": [
        "http://www.cidoc-crm.org/cidoc-crm/E18_Physical_Thing",
        "http://localhost:8000/graph/ab74af76-fa0e-11e6-9e3e-026d961c88e6"
    ],
    "http://www.cidoc-crm.org/cidoc-crm/P140i_was_attributed_by": {
        "@id": "http://localhost:8000/tile/1f7b4c8f-9932-47e4-9ec5-0284c77d893c/node/677f236e-09cc-11e7-8ff7-6c4008b05c4c",
        "@type": "http://www.cidoc-crm.org/cidoc-crm/E15_Identifier_Assignment",
        "http://www.cidoc-crm.org/cidoc-crm/P1_is_identified_by": [
            {
                "@id": "http://localhost:8000/tile/6efb8ac0-623c-47cb-9846-4a489c153683/node/677f303d-09cc-11e7-9aa6-6c4008b05c4c",
                "@type": "http://www.cidoc-crm.org/cidoc-crm/E41_Appellation",
                "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
                    "@id": "http://localhost:8000/tile/6efb8ac0-623c-47cb-9846-4a489c153683/node/677f39a8-09cc-11e7-834a-6c4008b05c4c",
                    "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "ecb20ae9-a457-4011-83bf-1c936e2d6b6a"
                },
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "Claudio"
            },
            {
                "@id": "http://localhost:8000/tile/b53f2aaa-348b-4b73-9ff9-195090038c8b/node/677f303d-09cc-11e7-9aa6-6c4008b05c4c",
                "@type": "http://www.cidoc-crm.org/cidoc-crm/E41_Appellation",
                "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
                    "@id": "http://localhost:8000/tile/b53f2aaa-348b-4b73-9ff9-195090038c8b/node/677f39a8-09cc-11e7-834a-6c4008b05c4c",
                    "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "81dd62d2-6701-4195-b74b-8057456bba4b"
                },
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "Alejandro"
            }
        ],
        "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
            "@id": "http://localhost:8000/tile/e818ecc5-8bde-4978-baca-2206a5bbf509/node/677f2c0f-09cc-11e7-b412-6c4008b05c4c",
            "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "e4699732-efee-46c0-87e1-3f0a930a43db"
        }
    }
}' \
'http://localhost:8000/resources/00131129-7451-435d-aab9-33eb9031e6d1?format=json-ld&indent=4'

Example json response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:8000/resource/47a1830c-74ec-11e8-bff6-14109fd34195",
    "@type": [
        "http://www.cidoc-crm.org/cidoc-crm/E18_Physical_Thing",
        "http://localhost:8000/graph/ab74af76-fa0e-11e6-9e3e-026d961c88e6"
    ],
    "http://www.cidoc-crm.org/cidoc-crm/P140i_was_attributed_by": {
        "@id": "http://localhost:8000/tile/1f7b4c8f-9932-47e4-9ec5-0284c77d893c/node/677f236e-09cc-11e7-8ff7-6c4008b05c4c",
        "@type": "http://www.cidoc-crm.org/cidoc-crm/E15_Identifier_Assignment",
        "http://www.cidoc-crm.org/cidoc-crm/P1_is_identified_by": [
            {
                "@id": "http://localhost:8000/tile/6efb8ac0-623c-47cb-9846-4a489c153683/node/677f303d-09cc-11e7-9aa6-6c4008b05c4c",
                "@type": "http://www.cidoc-crm.org/cidoc-crm/E41_Appellation",
                "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
                    "@id": "http://localhost:8000/tile/6efb8ac0-623c-47cb-9846-4a489c153683/node/677f39a8-09cc-11e7-834a-6c4008b05c4c",
                    "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "ecb20ae9-a457-4011-83bf-1c936e2d6b6a"
                },
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "Claudio"
            },
            {
                "@id": "http://localhost:8000/tile/b53f2aaa-348b-4b73-9ff9-195090038c8b/node/677f303d-09cc-11e7-9aa6-6c4008b05c4c",
                "@type": "http://www.cidoc-crm.org/cidoc-crm/E41_Appellation",
                "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
                    "@id": "http://localhost:8000/tile/b53f2aaa-348b-4b73-9ff9-195090038c8b/node/677f39a8-09cc-11e7-834a-6c4008b05c4c",
                    "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "81dd62d2-6701-4195-b74b-8057456bba4b"
                },
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "Alejandro"
            }
        ],
        "http://www.cidoc-crm.org/cidoc-crm/P2_has_type": {
            "@id": "http://localhost:8000/tile/e818ecc5-8bde-4978-baca-2206a5bbf509/node/677f2c0f-09cc-11e7-b412-6c4008b05c4c",
            "@type": "http://www.cidoc-crm.org/cidoc-crm/E55_Type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#value": "e4699732-efee-46c0-87e1-3f0a930a43db"
        }
    }
}

Surveys

GET /surveys

get a list of surveys/projects that a user has been invited to participate in

Example request:

curl -H "Authorization: Bearer {token}" -X GET http://localhost:8000/surveys

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM" -X GET http://localhost:8000/surveys

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

[
    {
        "active": true,
        "bounds": "MULTIPOLYGON EMPTY",
        "cards": [],
        "createdby_id": 1,
        "datadownloadconfig": {
            "count": 1000,
            "custom": null,
            "download": false,
            "resources": []
        },
        "description": "A description of this survey",
        "enddate": "2018-03-16",
        "groups": [
            6
        ],
        "id": "e3d95999-2323-11e8-894b-14109fd34195",
        "lasteditedby_id": 1,
        "name": "Forbidden Survey",
        "startdate": "2018-03-04",
        "tilecache": "",
        "users": [
            1
        ]
    }
]

Request Headers:  

• Authorization – JWT (JSON web token) for user authentication, see /auth/get_token