5. Restful Resources¶

5.1. Submit a claimant¶

Register a new claimant in the ClaimStore.

POST /api/claimants¶

This resource is expecting JSON data with all the necessary information of a new claimant.

Request:

POST /api/claimants HTTP/1.1
Content-Type: application/json
Host: localhost:5000

{
    "name": "INSPIRE",
    "url": "http://inspirehep.net"
}

Request Headers:
	Content-Type – application/json
JSON Parameters:
	body – JSON with the information of the claimant. The JSON data should be valid according to the JSON Schema for claimants.

Responses:

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

{
    "status": "success",
    "uuid": "ab19c98b-xxxx-xxxx-xxxx-1d6af3bf58b4"
}

HTTP/1.0 400 BAD REQUEST
Content-Length: 95
Content-Type: application/json

{
    "extra": null,
    "message": "This claimant is already registered",
    "status": 400
}

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error - the claimant was subscribed 400 Bad Request – invalid request - problably a malformed JSON 403 Forbidden – access denied

Usage:

From python:

import json
import requests

url = "http://localhost:5000/api/claimants/
headers = {"Content-Type": "application/json"}
with open(
    '$PROJECT_HOME/tests/config/claimants/cds.json'
) as f:
    data=json.dumps(f.read())
r = requests.post(url, data=data, headers=headers)

From httpie:

$ http POST http://localhost:5000/api/claimants < tests/myclaimstore/config/claimants/cds.json

From curl:

$ curl http://localhost:5000/api/claimants \
       -H "Content-Type: application/json" \
       -d @tests/myclaimstore/config/claimants/inspire.json -X POST -v

5.2. List claimants¶

GET service that returns all the available claimants.

GET /api/claimants/(uuid: claimant_id)¶

Returns a JSON list with all the claimants.

Request:

GET /api/claimants HTTP/1.1
Accept: */*
Host: localhost:5000

GET /api/claimants/0e64606e-68ce-482e-ad59-1e99... HTTP/1.1
Accept: */*
Host: localhost:5000

Request Headers:
	Content-Type – application/json

Response:

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

[
    {
        "name": "ADS",
        "url": "http://adsabs.harvard.edu/",
        "uuid": "00000000-be54-45c0-89fa-00000000"
    },
    {
        "name": "ARXIV",
        "url": "http://arxiv.org/",
        "uuid": "00000000-87a6-4095-99a9-00000000"
    },
    {
        "name": "CDS",
        "url": "http://cds.cern.ch",
        "uuid": "00000000-602e-4912-8a9b-00000000"
    },
    {
        "name": "INSPIRE",
        "url": "http://inspirehep.net",
        "uuid": "00000000-42a5-4d3f-b54a-00000000"
    }
]

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error 400 Bad Request – invalid request 403 Forbidden – access denied

Usage:

From python:

import requests
response = requests.get("http://localhost:5000/api/claimants")
print response.json()

From httpie:

$ http GET http://localhost:5000/api/claimants

From curl:

$ curl http://localhost:5000/api/claimants

5.3. Submit a claim¶

Record a new claim.

POST /api/claims¶

This resource is expecting JSON data with all the necessary information of a new claim.

Request:

POST /api/claims HTTP/1.1
Accept: application/json
Content-Length: 336
Content-Type: application/json

{
    "arguments": {
        "actor": "CDS_submission",
        "human": 0
    },
    "certainty": 1.0,
    "claimant": "CDS",
    "created": "2015-03-25T11:00:00Z",
    "object": {
        "type": "CDS_REPORT_NUMBER",
        "value": "CMS-PAS-HIG-14-008"
    },
    "predicate": "is_same_as",
    "subject": {
        "type": "CDS_RECORD_ID",
        "value": "2003192"
    }
}

Request Headers:
	Content-Type – application/json
JSON Parameters:
	body – JSON with the information of the claimt. The JSON data should be valid according to the JSON Schema for claims.

Responses:

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

{
    "status": "success",
    "uuid": "fad4ec9f-0e95-4a22-b65c-d01f15aba6be"
}

HTTP/1.0 400 BAD REQUEST
Content-Length: 9616
Content-Type: application/json
Date: Tue, 22 Sep 2015 09:02:25 GMT
Server: Werkzeug/0.10.4 Python/3.4.3

{
    "extra": "'claimant' is a required property. Failed
              validating 'required' in schema...",
    "message": "JSON data is not valid",
    "status": 400
}

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error - the claim was recorded 400 Bad Request – invalid request - problably a malformed JSON 403 Forbidden – access denied

Usage:

From python:

import json
import requests

url = "http://localhost:5000/api/claims/
headers = {"Content-Type": "application/json"}
with open(
    '$PROJECT_HOME/tests/config/claims/cds.1.json'
) as f:
    data=json.dumps(f.read())
r = requests.post(url, data=data, headers=headers)

From httpie:

$ http POST http://localhost:5000/api/claims < tests/myclaimstore/data/claims/cds.1.json

From curl:

$ curl http://localhost:5000/api/claims \
       -H "Content-Type: application/json" \
       -d @tests/myclaimstore/data/claims/inspire.1.json -X POST -v

5.4. List claims¶

GET service that returns the stored claims.

GET /api/claims/(uuid: claim_id)¶

Returns a JSON list with all the claims matching the query parameters.

Request:

GET /api/claims?type=CDS_RECORD_ID&value=cond-mat/9906097&
recurse=1 HTTP/1.1
Accept: */*
Host: localhost:5000

GET /api/claims/0e64606e-68ce-482e-ad59-1e9981394f HTTP/1.1
Accept: */*
Host: localhost:5000

Request Headers:
	Content-Type – application/json
Query Parameters:
	since (datetime) – it must have the format ‘YYYY-MM-DD’. It fetches claims that were created from this given datetime. until (datetime) – it must have the format ‘YYYY-MM-DD’. It fetches claims that were created up to this given datetime. claimant (string) – claimant’s unique name. It fetches claims submitted by the specified claimant. predicate (string) – predicate’s unique name. It finds claims using this predicate (e.g. is_same_as). certainty (float) – float number between 0 and 1.0. It will search for claims with at least the specified certainty. human (int) – enter 1 if searching for human-created claims, 0 for algorithms and nothing in order to retrieve all. actor (string) – it filters claims by their actor’s name (one can use %). role (string) – it filters claims by their actor’s role (one can use %). type (string) – it finds claims using a certain identifier type (either subject or object). For instance: DOI. value (string) – it fetches all the claims with that identifier value. recurse (boolean) – used in combination with type and value will find all the equivalent identifiers to the specified one. subject (string) – it fetches claims using the given identifier type as a subject type. object (string) – it fetches claims using the given identifier type as an object type. page (int) – page from which to fetch data. per_page (int) – amount of data per page.

Response:

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

[
    {
        "arguments": {
            "actor": "CDS_submission",
            "human": 0
        },
        "certainty": 1.0,
        "claimant": "CDS",
        "created": "2015-03-25T11:00:00Z",
        "object": {
            "type": "CDS_REPORT_NUMBER",
            "value": "CMS-PAS-HIG-14-008"
        },
        "predicate": "is_same_as",
        "recieved": "2015-09-22T08:18:30.606912+00:00",
        "subject": {
            "type": "CDS_RECORD_ID",
            "value": "2003192"
        },
        "uuid": "44103ee2-0d87-47f9-b0e4-77673d297cdb"
    },
    {
        "arguments": {
            "actor": "John Doe",
            "human": 1,
            "role": "cataloguer"
        },
        "certainty": 0.5,
        "claimant": "INSPIRE",
        "created": "2015-05-25T11:00:00Z",
        "object": {
            "type": "CDS_RECORD_ID",
            "value": "2003192"
        },
        "predicate": "is_variant_of",
        "recieved": "2015-09-22T08:18:30.638933+00:00",
        "subject": {
            "type": "INSPIRE_RECORD_ID",
            "value": "cond-mat/9906097"
        },
        "uuid": "27689445-02b9-4d5d-8f9b-da21970e2352"
    }
]

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error 400 Bad Request – invalid request 403 Forbidden – access denied

Usage:

From python:

import requests
response = requests.get("http://localhost:5000/api/claims")
print response.json()

From httpie:

$ http GET http://localhost:5000/api/claims

From curl:

$ curl http://localhost:5000/api/claims

5.5. List identifiers¶

GET service that returns the stored identifiers.

GET /api/identifiers¶

Returns a JSON list with all the available identifiers.

Request:

GET /api/identifiers HTTP/1.1
Accept: */*
Host: localhost:5000

Request Headers:
	Content-Type – application/json

Response:

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

[
    "ARXIV_ID",
    "CDS_AUTHOR_ID",
    "CDS_RECORD_ID",
    "CDS_REPORT_NUMBER",
    "DOI",
    "INSPIRE_AUTHOR_ID",
    "INSPIRE_RECORD_ID"
]

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error 400 Bad Request – invalid request 403 Forbidden – access denied

Usage:

From python:

import requests
response = requests.get("http://localhost:5000/api/identifiers")
print response.json()

From httpie:

$ http GET http://localhost:5000/api/identifiers

From curl:

$ curl http://localhost:5000/api/identifiers

5.6. List predicates¶

GET service that returns all the available predicates.

GET /api/predicates¶

Returns a JSON list with all the predicates.

Request:

GET /api/predicates HTTP/1.1
Accept: */*
Host: localhost:5000

Request Headers:
	Content-Type – application/json

Response:

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

[
    "is_author_of",
    "is_contributor_to",
    "is_erratum_of",
    "is_same_as",
    "is_variant_of"
]

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error 400 Bad Request – invalid request 403 Forbidden – access denied

Usage:

From python:

import requests
response = requests.get("http://localhost:5000/api/predicates")
print response.json()

From httpie:

$ http GET http://localhost:5000/api/predicates

From curl:

$ curl http://localhost:5000/api/predicates

5.7. List equivalent identifiers¶

GET service that returns all the stored Equivalent Identifiers.

GET /api/eqids/(uuid: eqid)¶

Returns all the type/value entries in the index grouped by their equivalent identifiers.

Requests:

GET /api/eqids HTTP/1.1
Accept: */*
Host: localhost:5000

GET /api/eqids/0e64606e-68ce-482e-ad59-1e9981394f8 HTTP/1.1
Accept: */*
Host: localhost:5000

Request Headers:
	Content-Type – application/json
Parameters:	eqid – query by a specific uuid which is shared by some equivalent identifiers

Response:

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

{
    "36dfb125-5c35-4d3a-870c-76eb4bad498e": [
        {
            "type": "ARXIV_ID",
            "value": "cond-mat/9906097"
        },
        {
            "type": "DOI",
            "value": "C10.1103/PhysRevE.62.7422"
        }
    ],
    "77c4a5eb-3ed8-4c80-ba0d-644d6bc397a3": [
        {
            "type": "CDS_RECORD_ID",
            "value": "2003192"
        },
        {
            "type": "CDS_REPORT_NUMBER",
            "value": "CMS-PAS-HIG-14-008"
        },
        {
            "type": "INSPIRE_RECORD_ID",
            "value": "cond-mat/9906097"
        }
    ]
}

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – no error 400 Bad Request – invalid request - problably a malformed UUID 403 Forbidden – access denied

Usage:

From python:

import requests
response = requests.get("http://localhost:5000/api/eqids")
print response.json()

From httpie:

$ http GET http://localhost:5000/api/eqids

From curl:
$ curl http://localhost:5000/api/eqids