Overview

This document describes the REST API of the Open Research Knowledge Graph.

HTTP verbs

The Open Research Knowledge Graph REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

The verbs PATCH, PUT, and DELETE are (currently) unsupported.

HTTP status codes

The Open Research Knowledge Graph REST API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

Statements

A statement represents a kind of sentence in the knowledge graph, similar to RDF triples. Similar to a real sentence, it is a tuple of a subject, a predicate, and a object.

Subjects and objects represent nodes in the graph are formed from a resource. Objects can also be a literal value.

Predicates represent edges (relationships) in the graph.

Resources and predicates are identifiable by an ID, whereas literals are not since they represent a value.

Statements can also be referenced by their IDs. This allows to store and retrieve provenance information about them.

Listing statements

A GET request lists all the statements:

Curl request

$ curl 'http://localhost:8080/api/statements/' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 918
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "S33",
  "subject" : {
    "id" : "R51",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P43",
    "label" : "blub"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R53",
    "label" : "three"
  }
}, {
  "id" : "S32",
  "subject" : {
    "id" : "R51",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P43",
    "label" : "blub"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R53",
    "label" : "three"
  }
}, {
  "id" : "S31",
  "subject" : {
    "id" : "R51",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P42",
    "label" : "blah"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R52",
    "label" : "two"
  }
}, {
  "id" : "S34",
  "subject" : {
    "id" : "R51",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P44",
    "label" : "to literal"
  },
  "object" : {
    "_class" : "literal",
    "id" : "L8",
    "label" : "literal"
  }
} ]

Creating statements

A POST request creates a new statement. The response will be 201 Created when successful. The statement can be retrieved by following the URI in the Location header field.

The created statement is returned in the body for convenience. This might be subject to change.

Creating statements can be done in two ways:

  1. For objects of type resource, send three IDs.

  2. For objects of type literal, send two IDs and the literal value in the body.

Creating statements with resource objects

Create a statement by submitting three IDs via POST:

Path parameters

Snippet path-parameters not found for operation::statement-controller-test-add-with-resource

Curl request
$ curl 'http://localhost:8080/api/statements/' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8' \
    -d '{
  "subject_id" : "R46",
  "predicate_id" : "P38",
  "object" : {
    "id" : "R47",
    "_class" : "resource"
  }
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/statements/
Content-Length: 229
Content-Type: application/json;charset=UTF-8

{
  "id" : "S26",
  "subject" : {
    "id" : "R46",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P38",
    "label" : "less than"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R47",
    "label" : "two"
  }
}

Fetching a statement

A GET request provides information about a statement.

Curl request

$ curl 'http://localhost:8080/api/statements/S27' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 224

{
  "id" : "S27",
  "subject" : {
    "id" : "R48",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P39",
    "label" : "blah"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R49",
    "label" : "two"
  }
}

Lookup statements by subject

A GET request lists all the statements with a given subject:

Curl request

$ curl 'http://localhost:8080/api/statements/subject/R43' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 456
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "S24",
  "subject" : {
    "id" : "R43",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P36",
    "label" : "blah"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R44",
    "label" : "two"
  }
}, {
  "id" : "S25",
  "subject" : {
    "id" : "R43",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P37",
    "label" : "blub"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R45",
    "label" : "three"
  }
} ]

Lookup statements by predicate

A GET request lists all the statements with a given predicate:

Curl request

$ curl 'http://localhost:8080/api/statements/predicate/P34' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 456
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "S21",
  "subject" : {
    "id" : "R40",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P34",
    "label" : "blah"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R41",
    "label" : "two"
  }
}, {
  "id" : "S22",
  "subject" : {
    "id" : "R40",
    "label" : "one"
  },
  "predicate" : {
    "id" : "P34",
    "label" : "blah"
  },
  "object" : {
    "_class" : "resource",
    "id" : "R42",
    "label" : "three"
  }
} ]

Resources

Resources represent nodes in the knowledge graph. They can appear in the subject or object position in statements.

Listing resources

A GET request lists all resources:

Curl request

$ curl 'http://localhost:8080/api/resources/' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 115
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "R38",
  "label" : "research contribution"
}, {
  "id" : "R39",
  "label" : "programming language"
} ]

Creating resources

A POST request creates a new resource with a given label. The response will be 201 Created when successful. The resource can be retrieved by following the URI in the Location header field.

The created resource is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The resource label

Curl request

$ curl 'http://localhost:8080/api/resources/' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8' \
    -d '{
  "label" : "foo"
}'

HTTP response

HTTP/1.1 201 Created
Location: http://localhost:8080/api/resources/R36
Content-Type: application/json;charset=UTF-8
Content-Length: 37

{
  "id" : "R36",
  "label" : "foo"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The resource ID

label

String

The resource label

Fetching a resource

A GET request provides information about a resource.

Curl request

$ curl 'http://localhost:8080/api/resources/R37' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 55
Content-Type: application/json;charset=UTF-8

{
  "id" : "R37",
  "label" : "research contribution"
}

Lookup a resource by label

Resources can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/resources/?q=research' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 109
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "R35",
  "label" : "research topic"
}, {
  "id" : "R33",
  "label" : "research contribution"
} ]

Predicates

Predicates represent edges (relationships between nodes) in the knowledge graph. They consist of an ID and a label (for presentation). IDs always start with "P", followed by a number.

Listing predicates

A GET request lists all predicates:

Curl request

$ curl 'http://localhost:8080/api/predicates/' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 87
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "P33",
  "label" : "knows"
}, {
  "id" : "P32",
  "label" : "has name"
} ]

Creating predicates

A POST request creates a new predicate with a given label. The response will be 201 Created when successful. The predicate can be retrieved by following the URI in the Location header field.

The created predicate is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The predicate label

Curl request

$ curl 'http://localhost:8080/api/predicates/' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8' \
    -d '{
  "label" : "knows"
}'

HTTP response

HTTP/1.1 201 Created
Content-Length: 39
Location: http://localhost:8080/api/predicates/P30
Content-Type: application/json;charset=UTF-8

{
  "id" : "P30",
  "label" : "knows"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The predicate ID

label

String

The predicate label

Fetching a predicate

A GET request provides information about a predicate.

Curl request

$ curl 'http://localhost:8080/api/predicates/P31' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 42
Content-Type: application/json;charset=UTF-8

{
  "id" : "P31",
  "label" : "has name"
}

Lookup a predicate by label

Predicates can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/predicates/?q=name' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 94
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "P27",
  "label" : "has name"
}, {
  "id" : "P28",
  "label" : "gave name to"
} ]

Literals

Literals represent nodes in the knowledge graph. They can appear in the object position in statements.

Listing Literals

A GET request lists all literals:

Curl request

$ curl 'http://localhost:8080/api/literals/' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 113

[ {
  "id" : "L5",
  "label" : "research contribution"
}, {
  "id" : "L6",
  "label" : "programming language"
} ]

Creating Literals

A POST request creates a new literal with a given label (its value). The response will be 201 Created when successful. The resource can be retrieved by following the URI in the Location header field.

The created literal is returned in the body for convenience. This might be subject to change.

Request fields

Path Type Description

label

String

The resource label

Curl request

$ curl 'http://localhost:8080/api/literals/' -i -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8' \
    -d '{
  "label" : "foo"
}'

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: http://localhost:8080/api/literals/L3
Content-Length: 36

{
  "id" : "L3",
  "label" : "foo"
}

The response body consists of the following fields:

Response fields

Path Type Description

id

String

The resource ID

label

String

The resource label

Fetching a literal

A GET request provides information about a literal.

Curl request

$ curl 'http://localhost:8080/api/literals/L4' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 54
Content-Type: application/json;charset=UTF-8

{
  "id" : "L4",
  "label" : "research contribution"
}

Lookup a literal by label

Literals can be looked up by label by providing a search fragment.

Curl request

$ curl 'http://localhost:8080/api/resources/?q=research' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=utf-8'

HTTP response

HTTP/1.1 200 OK
Content-Length: 109
Content-Type: application/json;charset=UTF-8

[ {
  "id" : "R35",
  "label" : "research topic"
}, {
  "id" : "R33",
  "label" : "research contribution"
} ]