Overview
This document describes the REST API of the Open Research Knowledge Graph.
This API is still in development and therefore unstable and subject to change! Be aware that the API can (and will) break without notice, so beware if you intend to consume it directly. We will support a stable API in the future, but it is uncertain when that will be. This documentation will be updated to reflect that. |
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 |
---|---|
|
Used to retrieve a resource |
|
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 |
---|---|
|
Standard response for successful HTTP requests.
The actual response will depend on the request method used.
In a |
|
The request has been fulfilled and resulted in a new resource being created. |
|
The server successfully processed the request, but is not returning any content. |
|
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). |
|
The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible. |
All responses with error codes that do not indicate success will contain a payload that describes the error. Their structure is documented in the section about Error representation.
Authentication (AuthN)
Authentication is done via the OAuth2 protocol. An authentication token needs to be obtained and provided to protected endpoints.
This endpoint only delivers information about the currenly logged in user. If you need to obtain information about other users in the system, check the Contributors section. |
Obtaining an access token
A token can be obtained by sending a POST
request to the /oauth/token
endpoint.
The client needs to provide its client ID and secret via basic authentication (base64-encoded).
All request parameters need to be passed in application/x-www-form-urlencoded
.
The parameters are:
grant_type
-
Always
password
. username
-
The email address of the user.
password
-
The password defined by the user.
The response will contain the access token and time of invalidation. Obtaining a new token is only possible by re-authenticating to the API.
Example:
curl -X POST --user 'orkg-client:secret' -d 'grant_type=password&username=user@example.org&password=password' http://localhost:8000/oauth/token
Command line users can save the token directly to a variable and use this in following requests. e.g. export TOKEN=$(curl --silent -X POST --user 'orkg-client:secret' -d 'grant_type=password&username=user@example.org&password=password' http://localhost:8000/oauth/token | jq -r '.access_token') |
Using the token
Tokens can be provided to the API via the Authorization
header field with the bearer
authentication type.
Authorization will be performed on tokens only.
Example:
curl -H "Accept: application/json" -H "Authorization: Bearer $TOKEN" -X GET http://localhost:8000/api/auth/user
Obtaining user information
User information about the currently logged-in user can be obtained from the /api/user/
endpoint via GET
requests.
An authentication token needs to be provided.
Other contributor information can be obtained individually from /api/user/{id}
, where {id}
is a UUID of the user.
This will only provide selected properties for display purposes; currently the ID and the display name.
Changing user information
User information can be changed via a PUT
request to the /api/user/
endpoint.
An authentication token needs to be provided.
To change the user name, the display_name
key needs to be present in the body.
Changing the password
Passwords can be changed via a PUT
request to the /api/user/password
endpoint.
An authentication token needs to be provided.
To change the password, the current_password
, new_password
and new_matching_password
keys need to be present in the body.
The current_password
must match the current password of the user.
Additionally, new_password
and new_matching_password
need to contain the same values.
Registering a user
New user accounts can be registered via a POST
request to the /api/auth/register
endpoint.
The email
, password
and matching_password
keys need to be provided in the request body.
An optional name
key can be provided to set the display name of the user (non-blank).
The endpoint will return the user data of the generated user.
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 an 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 storing and retrieving provenance information about them.
Listing statements
A GET
request lists all the statements:
Curl request
$ curl 'https://incubating.orkg.org/api/statements' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A comma-separated set of classes that the subject of the statement must have. The ids |
|
Filter for the subject id. (optional) |
|
Filter for the label of the subject. The label has to match exactly. (optional) |
|
Filter for the predicate id of the statement. (optional) |
|
Filter for the UUID of the user or service who created this statement. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned statement can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned statement can have. (optional) |
|
A comma-separated set of classes that the object of the statement must have. The ids |
|
Filter for the object id. (optional) |
|
Filter for the label of the object. The label has to match exactly. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/statements?subject_classes=Contribution%2CC123&subject_id=R1&subject_label=Default+Label&predicate_id=P1&created_by=34da5516-7901-4b0d-94c5-b062082e11a7&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&object_classes=Literal&object_id=L1&object_label=Default+Label' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination. |
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 response body contains the created statement for convenience. This might be subject to change. |
Creating statements can be done in two ways:
-
For objects of type resource, send three IDs.
-
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
:
Curl request
$ curl 'http://localhost:8080/api/statements/' -i -X POST \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"subject_id" : "R248",
"predicate_id" : "P16",
"object_id" : "R249"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/statements/
Content-Type: application/json
Content-Length: 1464
{
"created_at" : "2024-03-28T15:50:52.307274587Z",
"created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
"id" : "S470",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.145895722Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R249",
"label" : "two",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:52.14917043Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P16",
"label" : "less than",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.141863933Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R248",
"label" : "one",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
}
Deleting a statement
Delete a statement by providing the ID of the statement via a DELETE
call:
The response will be 204 No Content
when successful.
Curl request
$ curl 'https://incubating.orkg.org/api/statements/S1' -i -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 204 No Content
Fetching a statement
A GET
request provides information about a statement.
Curl request
$ curl 'http://localhost:8080/api/statements/S474' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1460
{
"created_at" : "2024-03-28T15:50:52.888721901Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"id" : "S474",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.702836784Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R255",
"label" : "two",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:52.860542181Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P19",
"label" : "blah",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.698837805Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R254",
"label" : "one",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
}
Fetching statements for a thing as a bundle
A GET
request that fetches the entire subgraph of a certain entity and returns all the statements as a bundle.
A Bundle
is a collection of statements that represents the sub-graph starting from a certain Thing
in the KG.
When fetching a bundle of statements, filtering is possible via specifying certain parameters in the request.
The number of levels in the tree being fetched can be filtered using the two query parameters minLevel
& minLevel
.
Furthermore, to be able to further control which statements to fetch, a black/white listing operation can be introduced via the query parameters blacklist
& whitelist
- this filter applies to classes of subjects and objects of statements only -
The endpoint also provide the parameter includeFirst
which by default is True
meaning it will not apply black/white listing on first level.
Curl request
$ curl 'http://localhost:8080/api/statements/R250/bundle' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4718
{
"root" : "R250",
"statements" : [ {
"created_at" : "2024-03-28T15:50:52.553425194Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"id" : "S473",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.488885066Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R253",
"label" : "four",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:52.496765903Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P17",
"label" : "blah",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.466271954Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R251",
"label" : "two",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
}
}, {
"created_at" : "2024-03-28T15:50:52.540686428Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"id" : "S472",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.474844831Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R252",
"label" : "three",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:52.50705142Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P18",
"label" : "blub",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.461867095Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R250",
"label" : "one",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
}, {
"created_at" : "2024-03-28T15:50:52.525185694Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"id" : "S471",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.466271954Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R251",
"label" : "two",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 1,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:52.496765903Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P17",
"label" : "blah",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:52.461867095Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R250",
"label" : "one",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ]
}
Bulk Statements
Bulk operations on statements. Helps performing multiple calls together.
Fetch by Subjects
A GET
request to get statements of multiple resources in the subject position.
Curl request
$ curl 'https://incubating.orkg.org/api/statements/subjects/?ids=R1,R3' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4510
[ {
"id" : "R1",
"statements" : {
"content" : [ {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S1",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R2",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P1",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R1",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 5,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 5,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
}, {
"id" : "R3",
"statements" : {
"content" : [ {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S2",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R4",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P2",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R3",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 5,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 5,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
} ]
Fetch by Objects
A GET
request to get statements of multiple resources/literals in the object position.
Curl request
$ curl 'https://incubating.orkg.org/api/statements/objects/?ids=R2,R4' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4510
[ {
"id" : "R2",
"statements" : {
"content" : [ {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S1",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R2",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P1",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R1",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 5,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 5,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
}, {
"id" : "R4",
"statements" : {
"content" : [ {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S2",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R4",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P2",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R3",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 5,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 5,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
} ]
Edit Statements
A PUT
request to edit multiple statements, with the same update body
Curl request
$ curl 'https://incubating.orkg.org/api/statements/?ids=S1,S2' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"predicate_id" : "P3",
"object_id" : "R5"
}'
Response fields
Path | Type | Description |
---|---|---|
|
|
The statement id |
|
|
The statement representation of the updated statement |
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3262
[ {
"id" : "S1",
"statement" : {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S1",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R5",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P3",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R1",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
}
}, {
"id" : "S2",
"statement" : {
"created_at" : "2023-10-02T15:32:18.753961+01:00",
"created_by" : "34da5516-7901-4b0d-94c5-b062082e11a7",
"id" : "S2",
"modifiable" : true,
"object" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R5",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"predicate" : {
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "P3",
"label" : "some predicate label",
"modifiable" : true
},
"subject" : {
"_class" : "resource",
"classes" : [ ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R3",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
}
} ]
Delete Statements
A DELETE
request to delete multiple statements simultaneously
Curl request
$ curl 'https://incubating.orkg.org/api/statements/?ids=S1,S2' -i -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 204 No Content
Classes
Classes represent concepts in the knowledge graph. They can be attached to resources to indicate that the resource belongs to the respective class.
Listing classes
A GET
request lists all classes:
Curl request
$ curl 'http://localhost:8080/api/classes/' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1004
{
"content" : [ {
"_class" : "class",
"created_at" : "2024-03-28T15:50:39.4642424Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "C5",
"label" : "research contribution",
"modifiable" : true,
"uri" : null
}, {
"_class" : "class",
"created_at" : "2024-03-28T15:50:39.474004756Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "C6",
"label" : "programming language",
"modifiable" : true,
"uri" : null
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Creating classes
A POST
request creates a new class with a given label.
An optional URI can be given to link to the class in an external ontology (RDF).
The response will be 201 Created
when successful.
The class can be retrieved by following the URI in the Location
header field.
The created class is returned in the body for convenience. This might be subject to change. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The class id (optional) |
|
|
The class label |
|
|
The class URI |
Curl request
$ curl 'https://incubating.orkg.org/api/classes/' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"id" : "C123",
"label" : "foo",
"uri" : "http://example.org/bar"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/classes/C123
Content-Type: application/json
Content-Length: 254
{
"_class" : "class",
"created_at" : "2023-10-05T12:29:15.3155145+01:00",
"created_by" : "dc8b2055-c14a-4e9f-9fcd-e0b79cf1f834",
"description" : null,
"id" : "C123",
"label" : "foo",
"modifiable" : true,
"uri" : "http://example.org/bar"
}
The response body consists of the following fields:
Response fields
Path | Type | Description |
---|---|---|
|
|
The class ID |
|
|
The class label |
|
|
An optional URI to describe the class (RDF) |
|
|
The class creation datetime |
|
|
The ID of the user that created the class. All zeros if unknown. |
|
|
The description of the class, if exists. |
|
|
Whether this class can be modified. |
Fetching a class
A GET
request provides information about a class.
Curl request
$ curl 'http://localhost:8080/api/classes/C4' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 247
{
"_class" : "class",
"created_at" : "2024-03-28T15:50:39.369049862Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "C4",
"label" : "research contribution",
"modifiable" : true,
"uri" : null
}
Lookup a class by label
Classes can be looked up by label by providing a search fragment.
Curl request
$ curl 'http://localhost:8080/api/classes/?q=research' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1000
{
"content" : [ {
"_class" : "class",
"created_at" : "2024-03-28T15:50:38.490756508Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "C2",
"label" : "research topic",
"modifiable" : true,
"uri" : null
}, {
"_class" : "class",
"created_at" : "2024-03-28T15:50:38.481696831Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "C0",
"label" : "research contribution",
"modifiable" : true,
"uri" : null
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Lookup resources by class
List all resources that are of the provided class type
Curl request
$ curl 'http://localhost:8080/api/classes/C10/resources/' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1537
{
"content" : [ {
"_class" : "resource",
"classes" : [ "C10" ],
"created_at" : "2024-03-28T15:50:39.940920839Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R244",
"label" : "Contribution 1",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}, {
"_class" : "resource",
"classes" : [ "C10" ],
"created_at" : "2024-03-28T15:50:40.147506209Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R245",
"label" : "Contribution 2",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Editing a class
A PATCH
request updates a class with a new given label and URI.
Only fields provided in the response, and therefore non-null, will be updated.
The response will be 200 OK
when successful.
Request fields
Path | Type | Description |
---|---|---|
|
|
The updated class label (optional) |
|
|
The updated class label (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/classes/EXISTS' -i -X PATCH \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"uri" : "https://example.org/some/new#URI",
"label" : "some label"
}'
HTTP response
HTTP/1.1 200 OK
A PUT
request updates a class with a new given label and URI.
All fields will be updated in the process.
The response will be 200 OK
when successful.
The updated class is returned in the body for convenience.
Request fields
Path | Type | Description |
---|---|---|
|
|
The updated class label |
|
|
The updated class label |
Curl request
$ curl 'https://incubating.orkg.org/api/classes/EXISTS' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"label" : "new label",
"uri" : "https://example.org/some/new#URI"
}'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 272
{
"_class" : "class",
"created_at" : "2023-10-05T12:29:15.3155145+01:00",
"created_by" : "dc8b2055-c14a-4e9f-9fcd-e0b79cf1f834",
"description" : null,
"id" : "EXISTS",
"label" : "new label",
"modifiable" : true,
"uri" : "https://example.org/some/new#URI"
}
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 'https://incubating.orkg.org/api/resources' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
The following two distinct sets of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the label. (optional) |
|
Whether label matching is exact or fuzzy (optional, default: false) |
|
Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional) |
|
Filter for the UUID of the user or service who created this resource. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional) |
|
A comma-separated set of classes that the resource must have. (optional) |
|
A comma-separated set of classes that the resource must not have. (optional) |
|
Filter for the UUID of the observatory that the resource belongs to. (optional) |
|
Filter for the UUID of the organization that the resource belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/resources?q=label&exact=true&visibility=ALL_LISTED&created_by=b7c81eed-52e1-4f7a-93bf-e6d331b8df7b&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&include=Include1%2CInclude2&exclude=Exclude1%2CExclude2&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Request parameters
Parameter | Description |
---|---|
|
The fuzzy search string for the label of the resource. |
|
The id of the base class that every resource has to be an instance of. |
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination. |
Creating resources
A POST
request creates a new resource with a given label.
An optional set of classes can be provided.
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 |
---|---|---|
|
|
The resource label. |
|
|
The classes of the resource. (optional) |
|
|
The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional, default: "UNKNOWN") |
Curl request
$ curl 'http://localhost:8080/api/resources/' -i -X POST \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"label" : "foo"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/resources/R5
Content-Type: application/json
Content-Length: 478
{
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:49.78068061Z",
"created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R5",
"label" : "foo",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
The response body consists of the following fields:
Response fields
Path | Type | Description |
---|---|---|
|
|
The resource ID |
|
|
The resource label |
|
|
The resource creation datetime |
|
|
The ID of the user that created the resource. All zeros if unknown. |
|
|
The list of classes the resource belongs to |
|
|
The ID of the observatory that maintains this resource. |
|
|
Method to extract this resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
|
|
The ID of the organization that maintains this resource. |
|
|
The number of times this resource is shared |
|
|
Class |
|
|
The formatted label of the resource if available |
Editing a resource
A PUT
request updates a resource with a new given label.
The response will be 200 OK
when successful.
The created resource is returned in the body for convenience.
Request fields
Path | Type | Description |
---|---|---|
|
|
The updated resource label. (optional) |
|
|
The classes to which the resource belongs to. (optional) |
|
|
The method used to extract the resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (optional) |
Curl request
$ curl 'http://localhost:8080/api/resources/R6' -i -X PUT \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"label" : "bar",
"classes" : [ "C3" ]
}'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 484
{
"_class" : "resource",
"classes" : [ "C3" ],
"created_at" : "2024-03-28T15:50:49.888588293Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R6",
"label" : "bar",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
Fetching a resource
A GET
request provides information about a resource.
Curl request
$ curl 'http://localhost:8080/api/resources/R7' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 497
{
"_class" : "resource",
"classes" : [ ],
"created_at" : "2024-03-28T15:50:50.176223786Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R7",
"label" : "research contribution",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
Delete a resource
A DELETE
request with the id of the resource to delete.
Note: This request is only acceptable if you have sufficient permissions.
a successful request return a No-Content HTTP status code.
Curl request
$ curl 'http://localhost:8080/api/resources/R1' -i -X DELETE \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 204 No Content
If the resource doesn’t exist, the API returns a 404 status code.
Curl request
$ curl 'http://localhost:8080/api/resources/NONEXISTENT' -i -X DELETE \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 188
{
"error" : "Not Found",
"message" : "Resource \"NONEXISTENT\" not found.",
"path" : "/api/resources/NONEXISTENT",
"status" : 404,
"timestamp" : "2024-03-28T15:50:50.31241628Z"
}
To safely delete a resource, the resource shouldn’t have any statements related to it. In this case a Forbidden HTTP status is returned.
Curl request
$ curl 'http://localhost:8080/api/resources/R2' -i -X DELETE \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 223
{
"error" : "Forbidden",
"message" : "Unable to delete resource \"R2\" because it is used in at least one statement.",
"path" : "/api/resources/R2",
"status" : 403,
"timestamp" : "2024-03-28T15:50:49.361167241Z"
}
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:
Request parameters
Parameter | Description |
---|---|
|
Page number of predicates to fetch (default: 1) |
|
Number of predicates to fetch per page (default: 10) |
|
Key to sort by (default: not provided) |
|
Direction of the sorting (default: false) |
Curl request
$ curl 'http://localhost:8080/api/predicates/' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 951
{
"content" : [ {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.516128278Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P10",
"label" : "knows",
"modifiable" : true
}, {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.512429369Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P9",
"label" : "has name",
"modifiable" : true
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
This is a paginated, and sortable call, check the table below for allowed keys for sorting Sorting and Pagination. |
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 response body contains the created predicate for convenience. This might be subject to change. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The id of the predicate. (optional) |
|
|
The label of the predicate. |
Curl request
$ curl 'https://incubating.orkg.org/api/predicates/' -i -X POST \
-H 'Content-Type: application/json' \
-d '{
"id" : null,
"label" : "predicate label"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/predicates/R123
Content-Type: application/json
Content-Length: 233
{
"_class" : "predicate",
"created_at" : "2023-10-04T13:30:16.931457+01:00",
"created_by" : "a56cfd65-8d29-4eae-a252-1b806fe88d3c",
"description" : null,
"id" : "R123",
"label" : "predicate label",
"modifiable" : true
}
The response body consists of the following fields:
Response fields
Path | Type | Description |
---|---|---|
|
|
The predicate id. |
|
|
The predicate label. |
|
|
The timestamp when the predicate was created. (Also see JavaDoc). |
|
|
The ID of the user that created the predicate. All zeros if unknown. |
|
|
The description of the predicate, if exists. |
|
|
Whether this predicate can be modified. |
Editing a predicate
A PUT
request updates a predicate with a new given label.
The response will be 200 OK
when successful.
The created predicate is returned in the body for convenience.
Curl request
$ curl 'http://localhost:8080/api/predicates/P7' -i -X PUT \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"label" : "yaser"
}'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 219
{
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.180891521Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P7",
"label" : "yaser",
"modifiable" : true
}
Fetching a predicate
A GET
request provides information about a predicate.
Curl request
$ curl 'http://localhost:8080/api/predicates/P8' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 222
{
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.475744161Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P8",
"label" : "has name",
"modifiable" : true
}
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 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 956
{
"content" : [ {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.002144931Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P4",
"label" : "has name",
"modifiable" : true
}, {
"_class" : "predicate",
"created_at" : "2024-03-28T15:50:41.00589546Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"description" : null,
"id" : "P5",
"label" : "gave name to",
"modifiable" : true
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Literals
Literals represent nodes in the knowledge graph. They can appear in the object position in statements.
Listing Literals
A GET
request returns a paged list of literals.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/literals/' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1162
{
"content" : [ {
"_class" : "literal",
"created_at" : "2022-10-30T11:13:10Z",
"created_by" : "39770c7d-ebff-1363-d0e7-4855d78e5847",
"datatype" : "DUInPBycd",
"id" : "L517",
"label" : "R34fDDkl",
"modifiable" : true
}, {
"_class" : "literal",
"created_at" : "2010-12-10T09:37:56Z",
"created_by" : "7cff033a-8cb3-4856-9015-b7a935cd9dfb",
"datatype" : "O",
"id" : "L387",
"label" : "v8vr7G7",
"modifiable" : true
}, {
"_class" : "literal",
"created_at" : "2013-11-02T01:37:21Z",
"created_by" : "dc47c870-26e8-9c65-f430-341c65e7dae6",
"datatype" : "hrNjuF",
"id" : "L8",
"label" : "kBtV1INPr",
"modifiable" : true
} ],
"empty" : false,
"first" : true,
"last" : false,
"number" : 0,
"numberOfElements" : 3,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 3,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 3,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 15,
"totalPages" : 5
}
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 |
---|---|---|
|
|
The updated value of the literal. |
|
|
The updated datatype of the literal value. |
Curl request
$ curl 'http://localhost:8080/api/literals/' -i -X POST \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"label" : "foo",
"datatype" : "xs:foo"
}'
HTTP response
HTTP/1.1 201 Created
Location: http://localhost:8080/api/literals/L164
Content-Type: application/json
Content-Length: 218
{
"_class" : "literal",
"created_at" : "2024-03-28T15:50:40.656448777Z",
"created_by" : "b7c81eed-52e1-4f7a-93bf-e6d331b8df7b",
"datatype" : "xs:foo",
"id" : "L164",
"label" : "foo",
"modifiable" : true
}
The response body consists of the following fields:
Response fields
Path | Type | Description |
---|---|---|
|
|
The resource ID |
|
|
The resource label |
|
|
The data type of the literal value. Defaults to |
|
|
The resource creation datetime |
|
|
The ID of the user that created the literal. All zeros if unknown. |
Editing a literal
A PUT
request updates a literal with a new value through the label property.
The response will be 200 OK
when successful.
The created literal is returned in the body for convenience.
Curl request
$ curl 'http://localhost:8080/api/literals/L165' -i -X PUT \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json' \
-d '{
"label" : "bar",
"datatype" : "dt:new"
}'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 218
{
"_class" : "literal",
"created_at" : "2024-03-28T15:50:40.725236474Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"datatype" : "dt:new",
"id" : "L165",
"label" : "bar",
"modifiable" : true
}
Fetching a literal
A GET
request provides information about a literal.
Curl request
$ curl 'https://incubating.orkg.org/api/literals/L1234' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 238
{
"_class" : "literal",
"created_at" : "2023-06-01T15:19:04.778631092+02:00",
"created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
"datatype" : "xsd:string",
"id" : "L1234",
"label" : "Default Label",
"modifiable" : true
}
Lookup a literal by label
Literals can be looked up by label by providing a search fragment.
Curl request
$ curl 'http://localhost:8080/api/literals/?q=research' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 982
{
"content" : [ {
"_class" : "literal",
"created_at" : "2024-03-28T15:50:40.504812969Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"datatype" : "xsd:string",
"id" : "L163",
"label" : "research topic",
"modifiable" : true
}, {
"_class" : "literal",
"created_at" : "2024-03-28T15:50:40.496791941Z",
"created_by" : "00000000-0000-0000-0000-000000000000",
"datatype" : "xsd:string",
"id" : "L161",
"label" : "research contribution",
"modifiable" : true
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Lists
Lists represent an ordered collection of statements in the knowledge graph. Their elements are defined by statement using the "has list element" predicate and a special "index" property, indicating the position in the list. The elements of a list can only be modified using the dedicated list endpoints.
Creating lists
A POST
request creates a new list with all the given parameters.
The response will be 201 Created
when successful.
The list resource (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the list. |
|
|
The ids of the elements of the list. |
Curl request
$ curl 'https://incubating.orkg.org/api/lists' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"label" : "List label",
"elements" : [ "R1" ]
}'
The response body consists of the following fields:
The created list resource is returned in the body for convenience. This might be subject to change. |
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/lists/R123
Content-Type: application/json
Content-Length: 224
{
"_class" : "list",
"created_at" : "2023-10-01T16:33:19.156943+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"elements" : [ "R1" ],
"id" : "R123",
"label" : "List label",
"modifiable" : true
}
Fetching a list
A GET
request provides information about a list.
Curl request
$ curl 'https://incubating.orkg.org/api/lists/R123' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 225
{
"_class" : "list",
"created_at" : "2023-06-01T15:19:04.778631092+02:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"elements" : [ ],
"id" : "R123",
"label" : "Default Label",
"modifiable" : true
}
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the list. |
|
|
The label of the list. |
|
|
The ids of the elements of the list. |
|
|
The timestamp when the list was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this list. |
|
|
Whether this list can be modified. |
|
|
The type of object this json contains. Always has the value "list". |
Fetching list elements
A GET
request returns a paged list of elements, in order, with their full representations (see resources, classes, predicates, literals), that are part of the list.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/lists/R123/elements' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Updating lists
A PATCH
request updates a list with all the given parameters.
The response will be 204 No Content
when successful.
Request fields
Path | Type | Description |
---|---|---|
|
|
The new label of the list. (optional) |
|
|
The new ids of the elements of the list. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/lists/List1' -i -X PATCH \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"label" : "List label",
"elements" : [ "R1" ]
}'
Papers
Papers represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a paper representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a paper
A GET
request provides information about a paper.
Curl request
$ curl 'https://incubating.orkg.org/api/papers/R8186' -i -X GET \
-H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.paper.v2+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the paper. |
|
|
The title of the paper. |
|
|
The list of research fields the paper is assigned to. |
|
|
The id of the research field. |
|
|
The label of the research field. |
|
|
The unique identifiers of the paper. |
|
|
The list of DOIs of the paper. (optional) |
|
|
The list of contributions of the paper. |
|
|
The ID of the contribution. |
|
|
The label of the contribution. |
|
|
The list of IDs of the organizations the paper belongs to. |
|
|
The list of IDs of the observatories the paper belongs to. |
|
|
The method used to extract the paper resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
|
|
The timestamp when the paper resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this paper. |
|
|
Determines if the paper was verified by a curator. |
|
|
Visibility of the paper. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED". |
|
|
Whether this paper can be modified. |
|
|
The UUID of the user or service who unlisted this paper. |
|
|
The list of authors that originally contributed to the paper. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The publication info of the paper. |
|
|
The month in which the paper was published. (optional) |
|
|
The year in which the paper was published. (optional) |
|
|
The venue where the paper was published. (optional) |
|
|
The ID of the venue. |
|
|
The label of the venue. |
|
|
The URL to the original paper. (optional) |
|
|
The list of sustainable development goals that the paper belongs to. |
|
|
The ID of the sustainable development goal. |
|
|
The label of the sustainable development goal. |
Listing papers
A GET
request returns a paged list of papers.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/papers' -i -X GET \
-H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.paper.v2+json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the title of the paper. (optional) |
|
Whether title matching is exact or fuzzy (optional, default: false) |
|
Filter for the DOI of the paper. (optional) |
|
Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". |
|
Filter for the verified flag of the paper. (optional) |
|
Filter for the UUID of the user or service who created this paper. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned paper can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned paper can have. (optional) |
|
Filter for the UUID of the observatory that the paper belongs to. (optional) |
|
Filter for the UUID of the organization that the paper belongs to. (optional) |
|
Filter for research field id. (optional) |
|
Flag for whether subfields are included in the search or not. (optional, default: false) |
|
Filter for the sustainable development goal that the paper belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/papers?title=label&exact=true&doi=10.456%2F8764&visibility=ALL_LISTED&verified=true&created_by=dca4080c-e23f-489d-b900-af8bfc2b0620&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f&research_field=R456&include_subfields=true&sdg=SDG_1' -i -X GET \
-H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.paper.v2+json'
Fetching contributors for a paper
A GET
request returns a paged list of contributor ids.
Curl request
$ curl 'https://incubating.orkg.org/api/papers/R8186/contributors' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Creating papers
A POST
request creates a new paper with all the given parameters.
The response will be 201 Created
when successful.
The paper (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The title of the paper. |
|
|
The list of research fields the paper will be assigned to. |
|
|
The unique identifiers of the paper. |
|
|
The DOI of the paper. (optional) |
|
|
The publication info of the paper. |
|
|
The month in which the paper was published. (optional) |
|
|
The year in which the paper was published. (optional) |
|
|
The venue where the paper was published. (optional) |
|
|
The URL to the original paper. (optional) |
|
|
The list of authors that originally contributed to the paper. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The set of ids of sustainable development goals the paper will be assigned to. (optional) |
|
|
Definition of the contents of the paper. |
|
|
Definition of resources that need to be created. |
|
|
The label of the resource. |
|
|
The list of classes of the resource. |
|
|
Definition of literals that need to be created. |
|
|
The value of the literal. |
|
|
The data type of the literal. |
|
|
Definition of predicates that need to be created. |
|
|
The label of the predicate. |
|
|
The description of the predicate. |
|
|
Definition of lists that need to be created. |
|
|
The label of the list. |
|
|
The IDs of the elements of the list. |
|
|
List of definitions of contribution that need to be created. |
|
|
Label of the contribution. |
|
|
The classes of the contribution resource. |
|
|
Recursive map of statements contained within the contribution. |
|
|
The ID of the object of the statement. |
|
|
The list of IDs of the organizations the paper belongs to. |
|
|
The list of IDs of the observatories the paper belongs to. |
|
|
The method used to extract the paper resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
Curl request
$ curl 'https://incubating.orkg.org/api/papers' -i -X POST \
-H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.paper.v2+json' \
-d '{
"authors" : [ {
"homepage" : null,
"id" : "R123",
"identifiers" : null,
"name" : "Author with id"
}, {
"homepage" : null,
"id" : null,
"identifiers" : {
"orcid" : [ "0000-1111-2222-3333" ]
},
"name" : "Author with orcid"
}, {
"homepage" : null,
"id" : "R456",
"identifiers" : {
"orcid" : [ "1111-2222-3333-4444" ]
},
"name" : "Author with id and orcid"
}, {
"homepage" : "http://example.org/author",
"id" : null,
"identifiers" : null,
"name" : "Author with homepage"
}, {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author that just has a name"
} ],
"contents" : {
"contributions" : [ {
"classes" : [ "C123" ],
"label" : "Contribution 1",
"statements" : {
"P32" : [ {
"id" : "R3003",
"statements" : null
} ],
"HAS_EVALUATION" : [ {
"id" : "#temp1",
"statements" : null
}, {
"id" : "R3004",
"statements" : {
"#temp3" : [ {
"id" : "R3003",
"statements" : null
}, {
"id" : "#temp2",
"statements" : null
}, {
"id" : "#temp4",
"statements" : null
} ],
"P32" : [ {
"id" : "#temp2",
"statements" : null
} ]
}
} ]
}
} ],
"lists" : {
"#temp4" : {
"elements" : [ "#temp1", "C123" ],
"label" : "list"
}
},
"literals" : {
"#temp2" : {
"data_type" : "xsd:decimal",
"label" : "0.1"
}
},
"predicates" : {
"#temp3" : {
"description" : "has result",
"label" : "hasResult"
}
},
"resources" : {
"#temp1" : {
"classes" : [ "Result" ],
"label" : "MOTO"
}
}
},
"extraction_method" : "MANUAL",
"identifiers" : {
"doi" : [ "10.48550 / arXiv.2304.05327" ]
},
"observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
"organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
"publication_info" : {
"published_in" : "conference",
"published_month" : 5,
"published_year" : 2015,
"url" : "https://www.example.org"
},
"research_fields" : [ "R12" ],
"sdgs" : [ "SDG_1" ],
"title" : "example paper"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/papers/R123
Editing a paper
A PUT
request updates an existing paper with all the given parameters.
The response will be 204 No Content
when successful.
The updated paper (object) can be retrieved by following the URI in the Location
header field.
All fields at the top level in the request can be omitted or null , meaning that the corresponding fields should not be updated.
|
Author names will not be updated if a resource id is specified for a given author. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The title of the paper. (optional) |
|
|
The list of research fields the paper will be assigned to. (optional) |
|
|
The unique identifiers of the paper. (optional) |
|
|
The DOI of the paper. (optional) |
|
|
The publication info of the paper. (optional) |
|
|
The month in which the paper was published. (optional) |
|
|
The year in which the paper was published. (optional) |
|
|
The venue where the paper was published. (optional) |
|
|
The URL to the original paper. (optional) |
|
|
The list of authors that originally contributed to the paper. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The set of ids of sustainable development goals the paper will be assigned to. (optional) |
|
|
The list of IDs of the organizations the paper belongs to. (optional) |
|
|
The list of IDs of the observatories the paper belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/papers/R123' -i -X PUT \
-H 'Content-Type: application/vnd.orkg.paper.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.paper.v2+json' \
-d '{
"authors" : [ {
"homepage" : null,
"id" : "R123",
"identifiers" : null,
"name" : "Author with id"
}, {
"homepage" : null,
"id" : null,
"identifiers" : {
"orcid" : [ "0000-1111-2222-3333" ]
},
"name" : "Author with orcid"
}, {
"homepage" : null,
"id" : "R456",
"identifiers" : {
"orcid" : [ "1111-2222-3333-4444" ]
},
"name" : "Author with id and orcid"
}, {
"homepage" : "http://example.org/author",
"id" : null,
"identifiers" : null,
"name" : "Author with homepage"
}, {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author that just has a name"
} ],
"identifiers" : {
"doi" : [ "10.48550/arXiv.2304.05327" ]
},
"observatories" : [ "1afefdd0-5c09-4c9c-b718-2b35316b56f3" ],
"organizations" : [ "edc18168-c4ee-4cb8-a98a-136f748e912e" ],
"publication_info" : {
"published_in" : "conference",
"published_month" : 5,
"published_year" : 2015,
"url" : "https://www.example.org"
},
"research_fields" : [ "R14" ],
"sdgs" : [ "SDG_3", "SDG_4" ],
"title" : "example paper"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/papers/R123
Publishing papers
A POST
request publishes an existing paper with the given parameters.
It assigns a DOI to the paper and adds additional publication information, such as month and year published.
The response will be 204 No Content
when successful.
Request fields
Path | Type | Description |
---|---|---|
|
|
The subject of the paper. |
|
|
The description of the paper. |
|
|
The list of authors that originally contributed to the paper. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list of ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/papers/R123/publish' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"subject" : "paper subject",
"description" : "paper description",
"authors" : [ {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author 1"
} ]
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/papers/R123
Contributions
Contributions represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts and provide a unified contribution representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a contribution
A GET
request provides information about a contribution.
Curl request
$ curl 'https://incubating.orkg.org/api/contributions/R15634' -i -X GET \
-H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.contribution.v2+json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.contribution.v2+json
Content-Length: 304
{
"classes" : [ "C123" ],
"created_at" : "2023-11-02T10:25:05.9595396+01:00",
"created_by" : "dca4080c-e23f-489d-b900-af8bfc2b0620",
"extraction_method" : "MANUAL",
"id" : "R15634",
"label" : "Contribution",
"properties" : {
"R456" : [ "R789", "R147" ]
},
"visibility" : "DEFAULT"
}
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the contribution. |
|
|
The label of the contribution. |
|
|
The classes of the contribution resource. |
|
|
A map of predicate ids to lists of thing ids, that represent the statements that this contribution consists of. |
|
|
The method used to extract the contribution resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
|
|
The timestamp when the contribution resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this contribution. |
|
|
Visibility of the contribution. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED". |
|
|
The UUID of the user or service who unlisted this contribution. |
Listing contributions
A GET
request returns a paged list of contributions.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/contributions' -i -X GET \
-H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.contribution.v2+json'
Creating contributions
A POST
request creates a new contribution with all the given parameters.
The response will be 201 Created
when successful.
The contribution (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The method used to extract the contribution resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". (default: "UNKNOWN") |
|
|
Definition of resources that need to be created. |
|
|
The label of the resource. |
|
|
The list of classes of the resource. |
|
|
Definition of literals that need to be created. |
|
|
The value of the literal. |
|
|
The data type of the literal. |
|
|
Definition of predicates that need to be created. |
|
|
The label of the predicate. |
|
|
The description of the predicate. |
|
|
Definition of lists that need to be created. |
|
|
The label of the list. |
|
|
The IDs of the elements of the list. |
|
|
List of definitions of contribution that need to be created. |
|
|
Label of the contribution. |
|
|
The classes of the contribution resource. |
|
|
Recursive map of statements contained within the contribution. |
|
|
The ID of the object of the statement. |
Curl request
$ curl 'https://incubating.orkg.org/api/papers/R3541/contributions' -i -X POST \
-H 'Content-Type: application/vnd.orkg.contribution.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.contribution.v2+json' \
-d '{
"contribution" : {
"classes" : [ "C123" ],
"label" : "Contribution 1",
"statements" : {
"P32" : [ {
"id" : "R3003",
"statements" : null
} ],
"HAS_EVALUATION" : [ {
"id" : "#temp1",
"statements" : null
}, {
"id" : "R3004",
"statements" : {
"#temp3" : [ {
"id" : "R3003",
"statements" : null
}, {
"id" : "#temp2",
"statements" : null
}, {
"id" : "#temp4",
"statements" : null
} ],
"P32" : [ {
"id" : "#temp2",
"statements" : null
} ]
}
} ]
}
},
"extraction_method" : "UNKNOWN",
"lists" : {
"#temp4" : {
"elements" : [ "#temp1", "C123" ],
"label" : "list"
}
},
"literals" : {
"#temp2" : {
"data_type" : "xsd:decimal",
"label" : "0.1"
}
},
"predicates" : {
"#temp3" : {
"description" : "has result",
"label" : "hasResult"
}
},
"resources" : {
"#temp1" : {
"classes" : [ "Result" ],
"label" : "MOTO"
}
}
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/contributions/R123
Comparisons
Comparisons represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a comparison representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a comparison
A GET
request provides information about a comparison.
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R8186' -i -X GET \
-H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the comparison. |
|
|
The title of the comparison. |
|
|
The description of the comparison. |
|
|
The list of research fields the comparison is assigned to. |
|
|
The id of the research field. |
|
|
The label of the research field. |
|
|
The unique identifiers of the comparison. |
|
|
The DOI of the comparison. (optional) |
|
|
The list of contributions of the comparison. |
|
|
The ID of the contribution. |
|
|
The label of the contribution. |
|
|
The list of visualizations of the comparison. |
|
|
The ID of the visualization. |
|
|
The label of the visualization. |
|
|
The list of related figures of the comparison. |
|
|
The ID of the related figure. |
|
|
The label of the related figure. |
|
|
The list of related resources of the comparison. |
|
|
The ID of the related resource. |
|
|
The label of the related resource. |
|
|
The list of references of the comparison. |
|
|
The list of IDs of the organizations the comparison belongs to. |
|
|
The list of IDs of the observatories the comparison belongs to. |
|
|
The method used to extract the comparison resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
|
|
The timestamp when the comparison resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this comparison. |
|
|
A sorted list by creation date of previous versions of the comparison. |
|
|
The ID of the resource of a previous version of the comparison. |
|
|
The label of a previous version of the comparison. |
|
|
The timestamp when the previous version of the comparison resource was created. (Also see JavaDoc). |
|
|
Whether or not the comparison is anonymized. |
|
|
Visibility of the comparison. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED". |
|
|
The UUID of the user or service who unlisted this comparison. |
|
|
The list of authors that originally contributed to the comparison. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The publication info of the paper. |
|
|
The month in which the comparison was published. (optional) |
|
|
The year in which the comparison was published. (optional) |
|
|
The venue where the comparison was published. (optional) |
|
|
The ID of the venue. |
|
|
The label of the venue. |
|
|
The URL to the original comparison. (optional) |
|
|
The list of sustainable development goals that the comparison belongs to. |
|
|
The ID of the sustainable development goal. |
|
|
The label of the sustainable development goal. |
Listing comparisons
A GET
request returns a paged list of comparisons.
If no paging request parameters are provided, the default values will be used.
Fetching comparisons by DOI, title or contributor does also return previous versions of comparisons. |
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons' -i -X GET \
-H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
The following list of request parameters are supported:
Request parameters
Snippet request-parameters not found for operation::comparisons-get-paged
Fetching a related resource for a comparison
A GET
request provides information about a comparison related resource.
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-resources/R1563' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the comparison related resource. |
|
|
The title of label comparison related resource. |
|
|
The url for the image of the comparison related resource. |
|
|
The url of the comparison related resource. |
|
|
The description of the comparison related resource. |
|
|
The timestamp when the comparison related resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this comparison related resource. |
Listing related resources for a comparison
A GET
request returns a paged list of comparison related resources.
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-resources' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
Fetching a related figure for a comparison
A GET
request provides information about a comparison related figure.
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-figures/R5476' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the comparison related figure. |
|
|
The title of label comparison related figure. |
|
|
The url for the image of the comparison related figure. |
|
|
The description of the comparison related figure. |
|
|
The timestamp when the comparison related figure was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this comparison related figure. |
Listing related figures for a comparison
A GET
request returns a paged list of comparison related figures.
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R123/related-figures' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json'
Creating comparisons
A POST
request creates a new comparison with all the given parameters.
The response will be 201 Created
when successful.
The comparison (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The title of the comparison. |
|
|
The description of the comparison. |
|
|
The list of research fields the comparison will be assigned to. |
|
|
The list of authors that originally contributed to the comparison. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The set of ids of sustainable development goals the comparison will be assigned to. (optional) |
|
|
The ids of the contributions the comparison compares. |
|
|
The references to external sources that the comparison refers to. |
|
|
The list of IDs of the organizations the comparison belongs to. |
|
|
The list of IDs of the observatories the comparison belongs to. |
|
|
Whether or not the comparison should be displayed as anonymous. |
|
|
The method used to extract the comparison resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons' -i -X POST \
-H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json' \
-d '{
"authors" : [ {
"homepage" : null,
"id" : "R123",
"identifiers" : null,
"name" : "Author with id"
}, {
"homepage" : null,
"id" : null,
"identifiers" : {
"orcid" : [ "0000-1111-2222-3333" ]
},
"name" : "Author with orcid"
}, {
"homepage" : null,
"id" : "R456",
"identifiers" : {
"orcid" : [ "1111-2222-3333-4444" ]
},
"name" : "Author with id and orcid"
}, {
"homepage" : "http://example.org/author",
"id" : null,
"identifiers" : null,
"name" : "Author with homepage"
}, {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author that just has a name"
} ],
"contributions" : [ "R6541", "R5364", "R9786", "R3120" ],
"description" : "comparison description",
"extraction_method" : "UNKNOWN",
"is_anonymized" : false,
"observatories" : [ "eeb1ab0f-0ef5-4bee-aba2-2d5cea2f0174" ],
"organizations" : [ "f9965b2a-5222-45e1-8ef8-dbd8ce1f57bc" ],
"references" : [ "https://orkg.org/resources/R1000", "paper citation" ],
"research_fields" : [ "R12" ],
"sdgs" : [ "SDG_1", "SDG_2" ],
"title" : "test"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R123
Creating comparison related resources
A POST
request creates a new comparison related resource with all the given parameters.
The response will be 201 Created
when successful.
The comparison related resource (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the comparison related resource. |
|
|
The url to the image of the comparison related resource. (optional) |
|
|
The url of the comparison related resource. (optional) |
|
|
The description of the comparison related resource. (optional) |
Path parameters
Parameter | Description |
---|---|
|
The comparison to attach the comparison related resource to. |
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-resources' -i -X POST \
-H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json' \
-d '{
"description" : "comparison related resource description",
"image" : "https://example.org/test.png",
"label" : "related resource",
"url" : "https://orkg.org/resources/R1000"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R100/related-resources/R123
Creating comparison related figures
A POST
request creates a new comparison related figure with all the given parameters.
The response will be 201 Created
when successful.
The comparison related figure (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the comparison related figure. |
|
|
The url to the image of the comparison related figure. (optional) |
|
|
The description of the comparison related figure. (optional) |
Path parameters
Parameter | Description |
---|---|
|
The comparison to attach the comparison related figure to. |
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R100/related-figures' -i -X POST \
-H 'Content-Type: application/vnd.orkg.comparison.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.comparison.v2+json' \
-d '{
"description" : "comparison related resource description",
"image" : "https://example.org/test.png",
"label" : "related resource"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/comparisons/R100/related-figures/R123
Publishing comparisons
A POST
request publishes an existing comparison with the given parameters.
It assigns a DOI to the comparison and adds additional publication information, such as month and year published.
The response will be 204 No Content
when successful.
Request fields
Path | Type | Description |
---|---|---|
|
|
The subject of the comparison. |
|
|
The description of the comparison. |
|
|
The list of authors that originally contributed to the comparison. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/comparisons/R123/publish' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"subject" : "comparison subject",
"description" : "comparison description",
"authors" : [ {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author 1"
} ]
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/comparisons/R123
Visualizations
Visualizations represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a visualization representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a visualization
A GET
request provides information about a visualization.
Curl request
$ curl 'https://incubating.orkg.org/api/visualizations/R8186' -i -X GET \
-H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.visualization.v2+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the visualization. |
|
|
The title of the visualization. |
|
|
The description of the visualization. |
|
|
The list of IDs of the organizations the visualization belongs to. |
|
|
The list of IDs of the observatories the visualization belongs to. |
|
|
The method used to extract the visualization resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
|
|
The timestamp when the visualization resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this visualization. |
|
|
Visibility of the visualization. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED". |
|
|
The UUID of the user or service who unlisted this visualization. |
|
|
The list of authors that originally contributed to the visualization. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
Listing visualizations
A GET
request returns a paged list of visualizations.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/visualizations' -i -X GET \
-H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.visualization.v2+json'
The following list of request parameters are supported:
Not all request parameters can be used in combination with others.
Only visibility , research_field and optionally include_subfields can be used together.
|
Request parameters
Parameter | Description |
---|---|
|
Optional filter for the title of the visualization. Uses exact matching. |
|
Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". |
|
Optional filter for the UUID of the user or service who created the visualization. |
|
Optional filter for research field id. |
|
Optional flag for whether subfields are included in the search or not. |
Creating visualizations
A POST
request creates a new visualization with all the given parameters.
The response will be 201 Created
when successful.
The visualization (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The title of the visualization. |
|
|
The description of the visualization. |
|
|
The list of authors that originally contributed to the visualization. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The list of IDs of the organizations the visualization belongs to. |
|
|
The list of IDs of the observatories the visualization belongs to. |
|
|
The method used to extract the visualization resource. Can be one of "UNKNOWN", "MANUAL" or "AUTOMATIC". |
Curl request
$ curl 'https://incubating.orkg.org/api/visualizations' -i -X POST \
-H 'Content-Type: application/vnd.orkg.visualization.v2+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.visualization.v2+json' \
-d '{
"authors" : [ {
"homepage" : null,
"id" : "R123",
"identifiers" : null,
"name" : "Author with id"
}, {
"homepage" : null,
"id" : null,
"identifiers" : {
"orcid" : [ "0000-1111-2222-3333" ]
},
"name" : "Author with orcid"
}, {
"homepage" : null,
"id" : "R456",
"identifiers" : {
"orcid" : [ "1111-2222-3333-4444" ]
},
"name" : "Author with id and orcid"
}, {
"homepage" : "http://example.org/author",
"id" : null,
"identifiers" : null,
"name" : "Author with homepage"
}, {
"homepage" : null,
"id" : null,
"identifiers" : null,
"name" : "Author that just has a name"
} ],
"description" : "visualization description",
"extraction_method" : "UNKNOWN",
"observatories" : [ "eeb1ab0f-0ef5-4bee-aba2-2d5cea2f0174" ],
"organizations" : [ "f9965b2a-5222-45e1-8ef8-dbd8ce1f57bc" ],
"title" : "test"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/visualizations/R123
Literature Lists
Literature Lists represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a literature list representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a literature list
A GET
request provides information about a literature list.
Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists/R658946' -i -X GET \
-H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.literature-list.v1+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the literature list. |
|
|
The title of the literature list. |
|
|
The list of research fields the literature list is assigned to. |
|
|
The id of the research field. |
|
|
The label of the research field. |
|
|
The head version of the literature list. |
|
|
The id of the head version. |
|
|
The label of the head version. |
|
|
The timestamp when the head version was created. (Also see JavaDoc). |
|
|
The list of published versions of the literature list. |
|
|
The id of the published version. |
|
|
The label of the published version. |
|
|
The timestamp when the published version was created. (Also see JavaDoc). |
|
|
The changelog of the published version. |
|
|
The list of IDs of the organizations the literature list belongs to. |
|
|
The list of IDs of the observatories the literature list belongs to. |
|
|
The method used to extract the literature list resource. Can be one of "unknown", "manual" or "automatic". |
|
|
The timestamp when the literature list resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this literature list. |
|
|
Visibility of the literature list. Can be one of "default", "featured", "unlisted" or "deleted". |
|
|
The UUID of the user or service who unlisted this literature list. |
|
|
Whether the literature is published or not. |
|
|
The list of sections of the literature list. |
|
|
The id of the section. |
|
|
The type of the section. Either of "text" or "list". |
|
|
The linked resources of a list section. |
|
|
The id of the linked resource. |
|
|
The label of the linked resource. |
|
|
The classes of the linked resource. |
|
|
The heading of the text section. |
|
|
The heading size of the text section. |
|
|
The text contents of the text section. |
|
|
The list of authors that originally contributed to the literature list. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The list of sustainable development goals that the literature list belongs to. |
|
|
The ID of the sustainable development goal. |
|
|
The label of the sustainable development goal. |
Listing literature lists
A GET
request returns a paged list of literature lists.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists' -i -X GET \
-H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.literature-list.v1+json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the title of the literature list. (optional) |
|
Whether title matching is exact or fuzzy (optional, default: false) |
|
Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". |
|
Filter for the UUID of the user or service who created this literature list. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional) |
|
Filter for the UUID of the observatory that the resource belongs to. (optional) |
|
Filter for the UUID of the organization that the resource belongs to. (optional) |
|
Filter for the publication status of the literature lists. (optional) |
|
Filter for the sustainable development goal that the literature list belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/literature-lists?title=label&exact=true&visibility=ALL_LISTED&created_by=c0afb083-1e54-461c-82e3-9641ef795ed7&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=ea49466b-726f-46c5-878f-c09be20fc0b8&organization_id=b72212d0-d457-4d55-ba2e-a53010cc6e19&published=true&sdg=SDG_1' -i -X GET \
-H 'Content-Type: application/vnd.orkg.literature-list.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.literature-list.v1+json'
Smart Reviews
Smart Reviews represent a collection of concepts in the knowledge graph. They can be seen as a collection of resources, literals and predicates. The provided endpoints aggregate these concepts into a smart review representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a smart review
A GET
request provides information about a smart review.
Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews/R1456' -i -X GET \
-H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.smart-review.v1+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the smart review. |
|
|
The title of the smart review. |
|
|
The list of research fields the smart review is assigned to. |
|
|
The id of the research field. |
|
|
The label of the research field. |
|
|
The head version of the smart review. |
|
|
The id of the head version. |
|
|
The label of the head version. |
|
|
The timestamp when the head version was created. (Also see JavaDoc). |
|
|
The list of published versions of the smart review. |
|
|
The id of the published version. |
|
|
The label of the published version. |
|
|
The timestamp when the published version was created. (Also see JavaDoc). |
|
|
The changelog of the published version. |
|
|
The list of IDs of the organizations the smart review belongs to. |
|
|
The list of IDs of the observatories the smart review belongs to. |
|
|
The method used to extract the smart review resource. Can be one of "unknown", "manual" or "automatic". |
|
|
The timestamp when the smart review resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this smart review. |
|
|
Visibility of the smart review. Can be one of "default", "featured", "unlisted" or "deleted". |
|
|
The UUID of the user or service who unlisted this smart review. |
|
|
Whether the literature is published or not. |
|
|
The list of sections of the smart review. |
|
|
The id of the section. |
|
|
The heading of the section. |
|
|
The type of the section. Either of "text", "comparison", "visualization", "resource", "property" or "ontology". |
|
|
The linked comparison of a comparison section. |
|
|
The id of the linked comparison. |
|
|
The label of the linked comparison. |
|
|
The classes of the linked comparison. |
|
|
The linked visualization of a visualization section. |
|
|
The id of the linked visualization. |
|
|
The label of the linked visualization. |
|
|
The classes of the linked visualization. |
|
|
The linked resource of a resource section. |
|
|
The id of the linked resource. |
|
|
The label of the linked resource. |
|
|
The classes of the linked resource. |
|
|
The linked resource of a predicate section. |
|
|
The id of the linked predicate. |
|
|
The label of the linked predicate. |
|
|
The description of the linked predicate. |
|
|
The entities that should be shown in the ontology section. They can either be a resource or a predicate. |
|
|
The id of the entity. |
|
|
The label of the entity. |
|
|
The classes of the entity, if the entity is a resource. |
|
|
The description of the entity, if the entity is a predicate. |
|
|
The predicates that should be shown in the ontology section. |
|
|
The id of the predicate. |
|
|
The label of the predicate. |
|
|
The description of the predicate. |
|
|
The text contents of the text section. |
|
|
The additional classes of the text section. |
|
|
The list of bibtex references of the smart review. |
|
|
The list of authors that originally contributed to the smart review. |
|
|
The ID of the author. (optional) |
|
|
The name of the author. |
|
|
The unique identifiers of the author. |
|
|
The list ORCIDs of the author. (optional) |
|
|
The list of Google Scholar IDs of the author. (optional) |
|
|
The list of ResearchGate IDs of the author. (optional) |
|
|
The list of LinkedIn IDs of the author. (optional) |
|
|
The list of Wikidata IDs of the author. (optional) |
|
|
The list of Web of Science IDs of the author. (optional) |
|
|
The homepage of the author. (optional) |
|
|
The list of sustainable development goals that the smart review belongs to. |
|
|
The ID of the sustainable development goal. |
|
|
The label of the sustainable development goal. |
Listing smart reviews
A GET
request returns a paged list of smart reviews.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews' -i -X GET \
-H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.smart-review.v1+json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the title of the smart review. (optional) |
|
Whether title matching is exact or fuzzy (optional, default: false) |
|
Optional filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". |
|
Filter for the UUID of the user or service who created this smart review. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned resource can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned resource can have. (optional) |
|
Filter for the UUID of the observatory that the resource belongs to. (optional) |
|
Filter for the UUID of the organization that the resource belongs to. (optional) |
|
Filter for the publication status of the smart reviews. (optional) |
|
Filter for the sustainable development goal that the smart review belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/smart-reviews?title=label&exact=true&visibility=ALL_LISTED&created_by=1cea89c6-d80b-4e39-b771-5541db028631&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=0cd69d1a-7277-4bff-bdde-036f6cb28e09&organization_id=e8c0e29e-08f4-4ae8-ae6c-ca0f08cc37c4&published=true&sdg=SDG_1' -i -X GET \
-H 'Content-Type: application/vnd.orkg.smart-review.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.smart-review.v1+json'
Templates
Templates represent a collection of concepts in the knowledge graph and can be seen as a collection of resources, literals and predicates. They can be used to define structures to research contribution data and can help illustrate what kind of data is needed to make the paper comparable. The provided endpoints aggregate these concepts into a template representation.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a template
A GET
request provides information about a template.
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R54631' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.v1+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the template. |
|
|
The label of the template. |
|
|
The description of the template. |
|
|
The formatted label pattern of the template. |
|
|
The target class of the template. |
|
|
The id of the target class. |
|
|
The label of the target class. |
|
|
The relations class of the template. Used for suggestions. |
|
|
The research fields that this template relates to. |
|
|
The id of the research field that this template relates to. |
|
|
The label of the research field that this template relates to. |
|
|
The research problems that this template relates to. |
|
|
The id of the research problem that this template relates to. |
|
|
The label of the research problem that this template relates to. |
|
|
The predicate that this template relates to. (optional) |
|
|
The id of the predicate that this template relates to. |
|
|
The label of the predicate that this template relates to. |
|
|
The properties of the template. |
|
|
The id of the property. |
|
|
The label of the property. |
|
|
The placeholder of the property. |
|
|
The description of the property. |
|
|
The order of the property. |
|
|
The minimum cardinality of the property. |
|
|
The maximum cardinality of the property. |
|
|
The pattern (regex) of the property. |
|
|
The predicate path of the property. |
|
|
The id of the predicate. |
|
|
The label of the predicate. |
|
|
The data type of the property, if the property is a literal property. |
|
|
The timestamp when the property was created.. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this property. |
|
|
The id of the data type. |
|
|
The label of the data type. |
|
|
The class range of the property, if the property is a literal property. |
|
|
The id of the class. |
|
|
The label of the class. |
|
|
Whether the template is closed or not. When a template is closed, its properties cannot be modified. |
|
|
The list of IDs of the organizations the template belongs to. |
|
|
The list of IDs of the observatories the template belongs to. |
|
|
The timestamp when the template resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this template. |
|
|
Visibility of the template. Can be one of "DEFAULT", "FEATURED", "UNLISTED" or "DELETED". |
|
|
The UUID of the user or service who unlisted this template. |
Listing templates
A GET
request returns a paged list of templates.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/templates' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.v1+json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the label of the template. (optional). |
|
Whether label matching is exact or fuzzy (optional, default: false) |
|
Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional) |
|
Filter for the UUID of the user or service who created the template. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned template can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned template can have. (optional) |
|
Filter for the UUID of the observatory that the template belongs to. (optional) |
|
Filter for the UUID of the organization that the template belongs to. (optional) |
|
Filter for research field id. (optional) |
|
Flag for whether subfields are included in the search or not. (optional, default: false) |
|
Filter for related research problem id. (optional) |
|
Filter for the target class. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/templates?q=label&exact=true&visibility=ALL_LISTED&created_by=dca4080c-e23f-489d-b900-af8bfc2b0620&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=cb71eebf-8afd-4fe3-9aea-d0966d71cece&organization_id=a700c55f-aae2-4696-b7d5-6e8b89f66a8f&research_field=R456&include_subfields=true&research_problem=R789&target_class=targetClass' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.v1+json'
Creating templates
A POST
request creates a new template with all the given parameters.
The response will be 201 Created
when successful.
The template (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the template. |
|
|
The description of the template. |
|
|
The formatted label pattern of the template. (optional) |
|
|
The target class of the template. |
|
|
The related resources of the template. This is used for suggestions. |
|
|
The list of research fields the template relates to. |
|
|
The list of research problems the template relates to. |
|
|
The predicate the template relates to. |
|
|
The property descriptions of the template. They can either be literal properties or resource properties. This is denoted by the |
|
|
The label of the property. |
|
|
The placeholder of the property. (optional) |
|
|
The description of the property. (optional) |
|
|
The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional) |
|
|
The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional) |
|
|
The pattern (regular expression) of the property. (optional) |
|
|
The predicate id for the path of the property. |
|
|
The class id of the range of the property, indicating a resource property. Mutually exclusive with |
|
|
The class id of the datatype of the property, indicating a literal property. Mutually exclusive with |
|
|
Whether the template is closed or not. When a template is closed, its properties cannot be modified. |
|
|
The list of IDs of the organizations the template belongs to. |
|
|
The list of IDs of the observatories the template belongs to. |
Curl request
$ curl 'https://incubating.orkg.org/api/templates' -i -X POST \
-H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.v1+json' \
-d '{
"description" : "Some description about the template",
"formatted_label" : "{P32}",
"is_closed" : true,
"label" : "Dummy Template Label",
"observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
"organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
"properties" : [ {
"datatype" : "C25",
"description" : "literal property description",
"label" : "literal property label",
"max_count" : 2,
"min_count" : 1,
"path" : "P24",
"pattern" : "\\d+",
"placeholder" : "literal property placeholder"
}, {
"class" : "C28",
"description" : "resource property description",
"label" : "resource property label",
"max_count" : 4,
"min_count" : 3,
"path" : "P27",
"pattern" : "\\w+",
"placeholder" : "resource property placeholder"
} ],
"relations" : {
"predicate" : "P22",
"research_fields" : [ "R20" ],
"research_problems" : [ "R21" ]
},
"target_class" : "targetClass"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R123
Editing a template
A PUT
request updates an existing template with all the given parameters.
The response will be 204 No Content
when successful.
The updated template (object) can be retrieved by following the URI in the Location
header field.
All fields at the top level in the request can be omitted or null , except for optional fields such as formatted_label , meaning that the corresponding fields should not be updated.
|
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the template. (optional) |
|
|
The description of the template. (optional) |
|
|
The formatted label pattern of the template. |
|
|
The target class of the template. (optional) |
|
|
The related resources of the template. This is used for suggestions. (optional) |
|
|
The list of research fields the template relates to. |
|
|
The list of research problems the template relates to. |
|
|
The predicate the template relates to. |
|
|
The property descriptions of the template. They can either be literal properties or resource properties. This is denoted by the |
|
|
The label of the property. |
|
|
The placeholder of the property. (optional) |
|
|
The description of the property. (optional) |
|
|
The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional) |
|
|
The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional) |
|
|
The pattern (regular expression) of the property. (optional) |
|
|
The predicate id for the path of the property. |
|
|
The class id of the range of the property, indicating a resource property. Mutually exclusive with |
|
|
The class id of the datatype of the property, indicating a literal property. Mutually exclusive with |
|
|
Whether the template is closed or not. When a template is closed, its properties cannot be modified. (optional) |
|
|
The list of IDs of the organizations the template belongs to. (optional) |
|
|
The list of IDs of the observatories the template belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R123' -i -X PUT \
-H 'Content-Type: application/vnd.orkg.template.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.v1+json' \
-d '{
"description" : "Some description about the template",
"formatted_label" : "{P32}",
"is_closed" : true,
"label" : "Dummy Template Label",
"observatories" : [ "cb71eebf-8afd-4fe3-9aea-d0966d71cece" ],
"organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
"properties" : [ {
"datatype" : "C25",
"description" : "literal property description",
"label" : "literal property label",
"max_count" : 2,
"min_count" : 1,
"path" : "P24",
"pattern" : "\\d+",
"placeholder" : "literal property placeholder"
}, {
"class" : "C28",
"description" : "resource property description",
"label" : "resource property label",
"max_count" : 4,
"min_count" : 3,
"path" : "P27",
"pattern" : "\\w+",
"placeholder" : "resource property placeholder"
} ],
"relations" : {
"predicate" : "P22",
"research_fields" : [ "R20" ],
"research_problems" : [ "R21" ]
},
"target_class" : "targetClass"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R123
Creating template properties
A POST
request creates a new template property with all the given parameters.
The response will be 201 Created
when successful.
The updated template (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the property. |
|
|
The placeholder of the property. (optional) |
|
|
The description of the property. (optional) |
|
|
The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. (optional) |
|
|
The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. (optional) |
|
|
The pattern (regular expression) of the property. (optional) |
|
|
The predicate id for the path of the property. |
|
|
The class id of the range of the property, indicating a resource property. Mutually exclusive with |
|
|
The class id of the datatype of the property, indicating a literal property. Mutually exclusive with |
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties' -i -X POST \
-H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.property.v1+json' \
-d '{
"datatype" : "C25",
"description" : "literal property description",
"label" : "literal property label",
"max_count" : 2,
"min_count" : 1,
"path" : "P24",
"pattern" : "\\d+",
"placeholder" : "literal property placeholder"
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/templates/R3541
Editing a template property
A PUT
request updates an existing template property with all the given parameters.
The response will be 204 No Content
when successful.
The updated template property (object) can be retrieved by following the URI in the Location
header field.
All fields at the top level in the request can be omitted or null , except for optional fields, meaning that the corresponding fields should not be updated.
|
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the property. |
|
|
The placeholder of the property. |
|
|
The description of the property. |
|
|
The minimum cardinality of the property. Must be at least one, or zero for infinite cardinality. |
|
|
The maximum cardinality of the property. Must be at least one, or zero for infinite cardinality. Must also be higher than min_count. |
|
|
The pattern (regular expression) of the property. |
|
|
The predicate id for the path of the property. |
|
|
The class id of the range of the property, indicating a resource property. Mutually exclusive with |
|
|
The class id of the datatype of the property, indicating a literal property. Mutually exclusive with |
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R3541/properties/R123' -i -X PUT \
-H 'Content-Type: application/vnd.orkg.template.property.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template.property.v1+json' \
-d '{
"datatype" : "C25",
"description" : "literal property description",
"label" : "literal property label",
"max_count" : 2,
"min_count" : 1,
"path" : "P24",
"pattern" : "\\d+",
"placeholder" : "literal property placeholder"
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R3541
Template Instances
Template instances are an abstraction for a subgraph of statements, which is defined by a template.
The following endpoints use content negotiation, meaning that the contents of the response json depend on the specified Accept and Content-Type headers of each request.
|
Fetching a template instance
A GET
request provides information about a template instance.
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R132/instances/R54631' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template-instance.v1+json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The resource representation of the root resource. |
|
|
Map of predicate id to list of embedded statement representations, where |
|
|
The thing representation of the object of the statement. Acts as the subject for statements defined in the |
|
|
The timestamp when the statement was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this statement. |
|
|
Map of predicate id to list of embedded statement representations, where |
HTTP response
HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.template-instance.v1+json
Content-Length: 1824
{
"root" : {
"_class" : "resource",
"classes" : [ "targetClass" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R54631",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
},
"statements" : {
"P24" : [ {
"created_at" : "2023-10-03T14:31:17.365491+01:00",
"created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
"statements" : { },
"thing" : {
"_class" : "literal",
"created_at" : "2023-10-03T14:31:17.365491+01:00",
"created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
"datatype" : "xsd:string",
"id" : "L1",
"label" : "Default Label",
"modifiable" : true
}
} ],
"P27" : [ {
"created_at" : "2023-10-03T14:31:17.365491+01:00",
"created_by" : "679ad2bd-ceb3-4f26-80ec-b6eab7a5e8c1",
"statements" : { },
"thing" : {
"_class" : "resource",
"classes" : [ "R28" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "R1",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ]
}
}
Listing template instances
A GET
request returns a paged list of template instances.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R132/instances' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template-instance.v1+json'
The following list of request parameters are supported:
Request parameters
Parameter | Description |
---|---|
|
A search term that must be contained in the label. (optional) |
|
Whether label matching is exact or fuzzy (optional, default: false) |
|
Filter for visibility. Either of "ALL_LISTED", "UNLISTED", "FEATURED", "NON_FEATURED", "DELETED". (optional) |
|
Filter for the UUID of the user or service who created this template instance. (optional) |
|
Filter for the created at timestamp, marking the oldest timestamp a returned template instance can have. (optional) |
|
Filter for the created at timestamp, marking the most recent timestamp a returned template instance can have. (optional) |
|
Filter for the UUID of the observatory that the template instance belongs to. (optional) |
|
Filter for the UUID of the organization that the template instance belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R132/instances?q=label&exact=true&visibility=ALL_LISTED&created_by=3599de15-5268-4f20-bad5-90f49ec549d9&created_at_start=2023-11-30T08%3A25%3A14.049085776%2B01%3A00&created_at_end=2023-11-30T10%3A25%3A14.049085776%2B01%3A00&observatory_id=ae9b200d-47d5-4488-ae5e-e2856f6248da&organization_id=07eed0a2-ab1b-462f-ba61-4b66cce534d9' -i -X GET \
-H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template-instance.v1+json'
Editing a template instance
A PUT
request updates an existing template instance with all the given parameters.
The response will be 204 No Content
when successful.
The updated template instance (object) can be retrieved by following the URI in the Location
header field.
Request fields
Path | Type | Description |
---|---|---|
|
|
Map of predicate ids to list of object ids that represent the statements of the template instance. |
|
|
Definition of resources that need to be created. |
|
|
The label of the resource. |
|
|
The list of classes of the resource. |
|
|
Definition of literals that need to be created. |
|
|
Key value pairs of literal temp ids to literal values. The type will be automatically assigned based on the template. |
|
|
Definition of predicates that need to be created. |
|
|
The label of the predicate. |
|
|
The description of the predicate. |
|
|
Definition of lists that need to be created. |
|
|
The label of the list. |
|
|
The IDs of the elements of the list. |
|
|
Definition of classes that need to be created. |
|
|
The label of the class. |
|
|
The uri of the class. |
|
|
The method used to extract the template instance. Can be one of "unknown", "manual" or "automatic". |
Curl request
$ curl 'https://incubating.orkg.org/api/templates/R123/instances/R456' -i -X PUT \
-H 'Content-Type: application/vnd.orkg.template-instance.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.template-instance.v1+json' \
-d '{
"classes" : {
"#temp5" : {
"label" : "class",
"uri" : "https://orkg.org/class/C1"
}
},
"extraction_method" : "MANUAL",
"lists" : {
"#temp4" : {
"elements" : [ "#temp1", "C123" ],
"label" : "list"
}
},
"literals" : {
"#temp2" : "0.1"
},
"predicates" : {
"#temp3" : {
"description" : "has result",
"label" : "hasResult"
}
},
"resources" : {
"#temp1" : {
"classes" : [ "Result" ],
"label" : "MOTO"
}
},
"statements" : {
"P27" : [ "#temp1", "#temp2", "#temp3" ],
"P24" : [ "#temp4", "#temp5", "R123" ]
}
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/templates/R123/instances/R456
RDF Integration
RDF Dump
The ORKG provides a dump of the entire graph in RDF, the dump is in N-Triples format.
Getting dump
This endpoint is deprecated. Clients are advised to update, because this endpoint will be removed in the future. |
Dumps cannot be created on-the-fly anymore, but can be downloaded from /files/rdf-dumps
.
The response will be 301 Moved Permanently
, pointing to the latest version of the dump.
Curl request
$ curl 'https://incubating.orkg.org/api/rdf/dump' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/n-triples'
HTTP response
HTTP/1.1 301 Moved Permanently
Location: https://incubating.orkg.org/files/rdf-dumps/rdf-export-orkg.nt
Resolvable Vocabulary
ORKG entities in RDF format are resolvable. Each URI refers to the description of the corresponding entity in some RDF serialization.
An RDF format media type can be provided via the Accept
header field.
For a list of supported media types, see Supported media types below.
Resolve a resource
A GET
request to get the description of an ORKG resource.
$ curl 'https://incubating.orkg.org/api/vocab/resource/R1' -i -X GET \
-H 'Accept: application/rdf+xml'
HTTP/1.1 200 OK
Content-Type: application/rdf+xml;charset=UTF-8
Content-Length: 535
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:r="http://orkg.org/orkg/resource/" xmlns:p="http://orkg.org/orkg/predicate/" xmlns:c="http://orkg.org/orkg/class/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">
<rdf:Description rdf:about="http://orkg.org/orkg/resource/R1">
<rdfs:label>Default Label</rdfs:label>
<rdf:type rdf:resource="http://orkg.org/orkg/class/Resource"/>
</rdf:Description>
</rdf:RDF>
Resolve a predicate
A GET
request to get the description of an ORKG predicate.
$ curl 'https://incubating.orkg.org/api/vocab/predicate/P1' -i -X GET \
-H 'Accept: text/n3'
HTTP/1.1 200 OK
Content-Type: text/n3;charset=UTF-8
Content-Length: 266
@prefix p: <http://orkg.org/orkg/predicate/> .
@prefix c: <http://orkg.org/orkg/class/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
p:P1 a c:Predicate;
rdfs:label "some predicate label" .
Resolve a class
A GET
request to get the description of an ORKG class.
$ curl 'https://incubating.orkg.org/api/vocab/class/C1' -i -X GET \
-H 'Accept: application/trig'
HTTP/1.1 200 OK
Content-Type: application/trig;charset=UTF-8
Content-Length: 313
@prefix c: <http://orkg.org/orkg/class/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
{
c:C1 a owl:Class;
rdfs:label "some label";
owl:equivalentClass "https://example.org/OK" .
}
Supported media types
Serialization to the following RDF media types is supported:
Media Type | Format |
---|---|
|
N-Triples |
|
RDF XML |
|
N3 |
|
JSON-LD |
|
TriG |
|
TriG |
|
N-Quads |
|
N-Quads |
|
N-Quads |
|
Turtle |
|
Turtle |
Contributors
Contributors are people contributing to the ORKG. They can become a member of an organization or join an observatory.
Obtaining contributor information
Information about a specific contributor can be obtained by sending a GET
request to the contributor endpoint:
Curl request
$ curl 'http://localhost:8080/api/contributors/acc6cd06-68f5-4c63-a906-2b13d1f9fb02' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Cache-Control: max-age=300
Content-Type: application/json
Content-Length: 395
{
"display_name" : "Some User",
"id" : "acc6cd06-68f5-4c63-a906-2b13d1f9fb02",
"joined_at" : "2024-03-28T15:49:17.951610621Z",
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"avatar_url" : "https://www.gravatar.com/avatar/9ab3be8f21fe883eeb99423a16618a34",
"gravatar_id" : "9ab3be8f21fe883eeb99423a16618a34"
}
The response contains the following fields:
Response fields
Path | Type | Description |
---|---|---|
|
|
The contributor ID. |
|
|
The name of the contributor. |
|
|
The time the contributor joined the project (in ISO 8601 format). |
|
|
The ID of the organization the contributor belongs to. All zeros if the contributor is not part of an organization. |
|
|
The ID of the observatory the contributor belongs to. All zeros if the contributor has not joined an observatory. |
|
|
The ID of the contributor on Gravatar. (Useful for generating profile pictures.) |
|
|
A URL to an avatar representing the user. Currently links to Gravatar. |
Organizations
Organizations represent institutes or groups. These can handle further smaller groups named Observatories.
Listing Organizations
A GET
request lists all organizations:
Curl request
$ curl 'http://localhost:8080/api/organizations/' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 273
[ {
"created_by" : "473af6d6-c0f3-4cc9-8012-64b2e668ba35",
"display_id" : "test_organization",
"homepage" : "https://www.example.org",
"id" : "d8743d71-73fd-4cfa-bd8a-1f7503e511cf",
"name" : "Test Organization",
"observatory_ids" : [ ],
"type" : "GENERAL"
} ]
Fetching an organization
A GET
request provides information about a resource.
Curl request
$ curl 'http://localhost:8080/api/organizations/c5197bce-5644-4f47-9a1f-87c162cfe2c7' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 269
{
"created_by" : "306d4410-d99e-4620-8acf-a2e5018b44f0",
"display_id" : "test_organization",
"homepage" : "https://www.example.org",
"id" : "c5197bce-5644-4f47-9a1f-87c162cfe2c7",
"name" : "Test Organization",
"observatory_ids" : [ ],
"type" : "GENERAL"
}
Observatories
Observatories are groups of experts affiliated with different institutions that curates and organize ORKG content for a specific discipline. Observatories represent groups which are managed by Organizations. One Observatory can be managed by many organizations.
Listing Observatories
A GET
request lists all organizations:
Curl request
$ curl 'http://localhost:8080/api/observatories/' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 828
{
"content" : [ {
"description" : "Example description",
"display_id" : "test_observatory",
"id" : "f1511c21-245e-4364-a4a2-4ed6809c3def",
"members" : [ ],
"name" : "Test Observatory",
"organization_ids" : [ "212e66e8-ceb1-47e6-8ac5-8cbf0d02710f" ],
"research_field" : {
"id" : "R5",
"label" : "label"
},
"sdgs" : [ ]
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Creating observatories
A POST
request creates a new observatory with the given parameters.
The response will be 201 Created
when successful.
The observatory can be retrieved by following the URI in the Location
header field.
The response body contains the created observatory for convenience. This might be subject to change. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The name of the observatory. Alternatively, the legacy field |
|
|
The id of the organization that the observatory belongs to. |
|
|
The description of the observatory. |
|
|
The id of the research field of the observatory. |
|
|
The URI slug of the observatory. |
|
|
The set of ids of sustainable development goals the observatory belongs to. |
Curl request
$ curl 'https://incubating.orkg.org/api/observatories' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"description" : "Example Description",
"display_id" : "test_observatory",
"name" : "Test Observatory",
"organization_id" : "a700c55f-aae2-4696-b7d5-6e8b89f66a8f",
"research_field" : "R1234",
"sdgs" : [ "SDG1" ]
}'
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33
Content-Type: application/json
Content-Length: 347
{
"description" : "Example Description",
"display_id" : "test_observatory",
"id" : "95565e51-2b80-4c28-918c-6fbc5e2a9b33",
"members" : [ ],
"name" : "Test Observatory",
"organization_ids" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
"research_field" : {
"id" : "R1234",
"label" : "Default Label"
},
"sdgs" : [ "SDG1" ]
}
Fetching an observatory
A GET
request provides information about a resource.
Curl request
$ curl 'http://localhost:8080/api/observatories/b2be546c-30a2-45d0-99ce-f6b0f2949d18' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 329
{
"description" : "Example description",
"display_id" : "test_observatory",
"id" : "b2be546c-30a2-45d0-99ce-f6b0f2949d18",
"members" : [ ],
"name" : "Test Observatory",
"organization_ids" : [ "80dc9ec1-91fb-4f14-9e2e-de8eacdc4adb" ],
"research_field" : {
"id" : "R4",
"label" : "label"
},
"sdgs" : [ ]
}
Editing an observatory
A PATCH
request updates an existing observatory with the given parameters.
Only fields provided in the response, and therefore non-null, will be updated.
The response will be 204 No Content
when successful.
The updated observatory (object) can be retrieved by following the URI in the Location
header field.
This endpoint can only be accessed by curators. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The new name of the observatory. (optional) |
|
|
The new set of organizations that the observatory belongs to. (optional) |
|
|
The new description of the observatory. (optional) |
|
|
The id of the new research field of the observatory. (optional) |
|
|
The new set of ids of sustainable development goals that the observatory belongs to. (optional) |
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/73b2e081-9b50-4d55-b464-22d94e8a25f6' -i -X PATCH \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"description" : "new observatory description",
"name" : "updated",
"organizations" : [ "a700c55f-aae2-4696-b7d5-6e8b89f66a8f" ],
"research_field" : "R123",
"sdgs" : [ "SDG1" ]
}'
HTTP response
HTTP/1.1 204 No Content
Location: https://incubating.orkg.org/api/observatories/73b2e081-9b50-4d55-b464-22d94e8a25f6
Listing papers of an observatory
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/deaab9d4-4c5a-4062-b3b7-1058eaacf352/papers?visibility=FEATURED&filter_config=%5B%7B%22exact%22%3Atrue%2C%22path%22%3A%5B%7B%22value%22%3A%22P105027%22%7D%5D%2C%22range%22%3A%7B%22value%22%3A%22String%22%7D%2C%22values%22%3A%5B%7B%22op%22%3A%22EQ%22%2C%22value%22%3A%22yes%22%7D%5D%7D%2C%7B%22exact%22%3Afalse%2C%22path%22%3A%5B%7B%22value%22%3A%22P32%22%7D%5D%2C%22range%22%3A%7B%22value%22%3A%22Resources%22%7D%2C%22values%22%3A%5B%7B%22op%22%3A%22EQ%22%2C%22value%22%3A%22R1234%22%7D%5D%7D%5D' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Request parameters
Parameter | Description |
---|---|
|
The filter config to use. (optional) |
|
Visibility of this resource. Can be one of "listed", "featured", "unlisted" or "deleted". (optional) |
This call features filter configs, check the chapter Filter Configs for more information on filter configs. |
Sorting is supported for the following fields: id , created_by , created_at .
It is also possible to sort by the matched value of each search filter.
To sort by the first search filter, the parameter value0 can be used.
If a second search filter is defined, the parameter value1 can be used.
By default, elements are sorted by created_at (descending).
|
Observatory Filters
Observatory filters are persistent filter configurations (presets) for observatories.
Fetching an Observatory Filter
A GET
request provides information about an observatory filter, which always belongs to a specific observatory.
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Path parameters
Parameter | Description |
---|---|
|
The identifier of the observatory that the filter belongs to. |
|
The identifier of the filter to retrieve. |
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the filter. |
|
|
The id of the observatory that the filter belongs to. |
|
|
The label of the filter. |
|
|
Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. |
|
|
The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching. |
|
|
Whether to exactly match the given path. If |
|
|
The timestamp when the filter was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this filter. |
|
|
Whether the filter is featured or not. |
Listing Observatory Filters
A GET
request returns a paged list of observatory filters that belong to the specified observatory.
If no paging request parameters are provided, the default values will be used.
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Path parameters
Parameter | Description |
---|---|
|
The identifier of the observatory that the filters belongs to. |
Creating Observatory Filters
A POST
request creates a new observatory filter with the given parameters.
The response will be 201 Created
when successful.
The observatory filter can be retrieved by following the URI in the Location
header field.
The user performing the action needs to be a curator or a member of the observatory. |
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"label" : "filter",
"path" : [ "P32" ],
"range" : "Resources",
"exact" : false,
"featured" : false
}'
Path parameters
Parameter | Description |
---|---|
|
The identifier of the observatory that the filters belongs to. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The label of the filter. |
|
|
Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. |
|
|
The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching. |
|
|
Whether to exactly match the given path. If |
|
|
Whether or not the filter is featured. (optional) |
HTTP response
HTTP/1.1 201 Created
Location: https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/c6b41f1e-ee46-48ea-8d47-57ce85760831
Updating Observatory Filters
A PATCH
request updates an existing observatory filter with the given parameters.
The response will be 204 No Content
when successful.
The user performing the action needs to be a curator or a member of the observatory. |
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/ee133f41-d060-4f87-bca6-70cb870a9879' -i -X PATCH \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json' \
-d '{
"label" : "filter",
"path" : [ "P32" ],
"range" : "Resources",
"exact" : false,
"featured" : false
}'
Path parameters
Parameter | Description |
---|---|
|
The identifier of the observatory that the filters belongs to. |
|
The identifier of the filter to update. |
Request fields
Path | Type | Description |
---|---|---|
|
|
The new label of the filter. (optional) |
|
|
Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. (optional) |
|
|
The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching. (optional) |
|
|
Whether to exactly match the given path. If |
|
|
Whether or not the filter is featured. (optional) |
HTTP response
HTTP/1.1 204 No Content
Deleting Observatory Filters
A DELETE
request deletes an observatory filter.
The response will be 204 No Content
when successful.
The user performing the action needs to be a curator or a member of the observatory. |
Curl request
$ curl 'https://incubating.orkg.org/api/observatories/95565e51-2b80-4c28-918c-6fbc5e2a9b33/filters/009f0193-08f1-4d5c-ac07-5b38331c5e84' -i -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Path parameters
Parameter | Description |
---|---|
|
The identifier of the observatory that the filters belongs to. |
|
The identifier of the filter to delete. |
HTTP response
HTTP/1.1 204 No Content
Research Problems
Research problems in the ORKG are important concepts and thus have their own API enpoint to get all related concepts.
Fields per problem
A GET
request get all research fields relating to a problem
Users per problem
A GET
request to get a paginated list of ORKG users that contributed to contributions where a problem is being addressed.
Curl request
$ curl 'http://localhost:8080/api/problems/R220/users?size=4' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 453
[ {
"contributions" : 1,
"user" : {
"display_name" : "test_user",
"id" : "3cda5502-94a7-4780-943f-6b9e9f325475",
"joined_at" : "2024-03-28T15:50:30.405005966Z",
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"avatar_url" : "https://www.gravatar.com/avatar/909c3113e76a1d52913c88135fbb431e",
"gravatar_id" : "909c3113e76a1d52913c88135fbb431e"
}
} ]
Response fields
Path | Type | Description |
---|---|---|
|
|
A list of users |
|
|
The user object |
|
|
The UUID of the user in the system |
|
|
The gravatar id of the user |
|
|
The user’s display name |
|
|
The user’s avatar url (gravatar url) |
|
|
the datetime when the user was created |
|
|
the organization id that this user belongs to |
|
|
the observatory id that this user belongs to |
|
|
The number of contributions this user created |
Authors per problem
A GET
request provides a paginated list of authors that have papers addressing a certain research problem
Research Fields
Research fields are meta-objects that help better classify the content within the ORKG. The research field is essentially a resource and hence inherits all the specifications of resource.
All GET
requests share the same path parameter, listed below, and support visibility filtering.
The responses are paged.
Path parameters
Parameter | Description |
---|---|
|
The ID of the research field. |
In the following sections, the response fields of the page object are omitted for brevity. |
Research fields and content types
Fetching content types of a research field
A GET
request for a given research field returns a paged list of content type resources that belong to this research field.
Certain subsets of content types are obtained via the classes
parameter.
The endpoint supports Visibility filtering (obsolete).
Path parameters
Parameter | Description |
---|---|
|
The ID of the research field. |
Request parameters
Parameter | Description |
---|---|
|
A list of classes to filter against. The classes must support research fields. Must be one of |
|
Return only featured results. Defaults to |
|
Return only unlisted results. Defaults to |
|
The visibility modifier. Must be one of |
Response fields
Path | Type | Description |
---|---|---|
|
|
A (sorted) array of content type resources. |
Fetching content types of a research field and its subfields
A GET
request to /api/research-fields/{id}/subfields
returns a paged list of content type resources belonging to a given research field and its subfields.
All path, request and response parameters are exactly the same as on the endpoint without subfields.
Research fields and research problems
Listing research problems of a research field
A GET
request to /api/research-fields/{id}/problems
lists all research problems used within all papers under the specified research field, along with their paper count.
The endpoint supports Visibility filtering (obsolete).
Response fields
Path | Type | Description |
---|---|---|
|
|
A (sorted) array of problems and paper counts (see below). |
The response objects have the following form:
Path | Type | Description |
---|---|---|
|
|
A research problem resource, i. e. a resource of class |
|
|
The number of papers that address this research problem. |
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/problems' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 892
{
"content" : [ {
"papers" : 5,
"problem" : {
"_class" : "resource",
"classes" : [ "Problem" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "RP234",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Listing Problems in field including sub research fields
A GET
request to /api/research-fields/{id}/subfields/research-problems
returns a paged list of research problem resources belonging to a given research field and its subfields.
All path and request parameters are exactly the same as on the endpoint without subfields.
Research fields and papers
Listing Papers of a research field
A GET
request to /api/research-fields/{id}/papers
returns a paged list of paper resources belonging to a given research field.
Response fields
Path | Type | Description |
---|---|---|
|
|
A (sorted) array of paper resources. |
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/papers' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1373
{
"content" : [ {
"_class" : "resource",
"classes" : [ "Paper" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "P1",
"label" : "Some interesting title",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 12,
"unlisted" : false,
"verified" : false
}, {
"_class" : "resource",
"classes" : [ "Paper" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "P2",
"label" : "Even more interesting title",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 13,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : "INSTANCE",
"size" : 2,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Listing Papers of a research field and its subfields
A GET
request to /api/research-fields/{id}/subfields/papers
returns a paged list of paper resources belonging to a given research field and its subfields.
All path and request parameters are exactly the same as on the endpoint without subfields.
Research fields and contributors
Listing Contributors of a research field
A GET
request to /api/research-fields/{id}/contributors
returns a paged list of contributors that contributed to a given research field.
This endpoint does not support visibility filtering!
The only supported path parameter is featured .
|
Response fields
Path | Type | Description |
---|---|---|
|
|
A (sorted) array of contributors. |
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/contributors' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1021
{
"content" : [ {
"display_name" : "Some One",
"id" : "3a6b2e25-5890-44cd-b6e7-16137f8b9c6a",
"joined_at" : "2023-10-06T10:37:17.055493+01:00",
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"avatar_url" : "https://www.gravatar.com/avatar/?d=mp&f=y",
"gravatar_id" : "?d=mp&f=y"
}, {
"display_name" : "Another One",
"id" : "fd4a1478-ce49-4e8e-b04a-39a8cac9e33f",
"joined_at" : "2023-10-06T10:37:17.055493+01:00",
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"avatar_url" : "https://www.gravatar.com/avatar/?d=mp&f=y",
"gravatar_id" : "?d=mp&f=y"
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : "INSTANCE",
"size" : 2,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Listing Contributors of a research field and its subfields
A GET
request to /api/research-fields/{id}/subfields/contributors
returns a paged list of contributors that contributed to a given research field and its subfields.
All path and request parameters are exactly the same as on the endpoint without subfields.
Research fields and comparisons
Listing comparisons of a research field
A GET
request to /api/research-fields/{id}/comparisons
returns a paged list of comparison resources belonging to a given research field.
Response fields
Path | Type | Description |
---|---|---|
|
|
A (sorted) array of comparison resources. |
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/RF1234/comparisons' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1360
{
"content" : [ {
"_class" : "resource",
"classes" : [ "Comparison" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "P1",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 12,
"unlisted" : false,
"verified" : false
}, {
"_class" : "resource",
"classes" : [ "Comparison" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "P2",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 13,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : "INSTANCE",
"size" : 2,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Listing comparisons of a research field and its subfields
A GET
request to /api/research-fields/{id}/subfields/comparisons
returns a paged list of comparison resources belonging to a given research field and its subfields.
All path and request parameters are exactly the same as on the endpoint without subfields.
Listing subfields
A GET
request lists all sub research fields of a research field.
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/R123/children' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 907
{
"content" : [ {
"child_count" : 1,
"resource" : {
"_class" : "resource",
"classes" : [ "ResearchField" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "subfield",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Path | Type | Description |
---|---|---|
|
|
The count of direct subfields that this research field has. |
|
|
Resource representation of the research field resource. |
Listing parent research fields
A GET
request lists all parent research fields of a research field.
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/R123/parents' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 827
{
"content" : [ {
"_class" : "resource",
"classes" : [ "ResearchField" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "parent",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Listing root research fields of a subfield
A GET
request lists all root research fields of the specified research field.
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/subfield/roots' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 825
{
"content" : [ {
"_class" : "resource",
"classes" : [ "ResearchField" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "root",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Listing all root research fields
A GET
requests lists all root research fields.
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/roots' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 825
{
"content" : [ {
"_class" : "resource",
"classes" : [ "ResearchField" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "root",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Listing research field hierarchy
A GET
request lists all paths from root research fields to the specified research field.
Curl request
$ curl 'https://incubating.orkg.org/api/research-fields/subfield/hierarchy' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 917
{
"content" : [ {
"parent_ids" : [ "parent" ],
"resource" : {
"_class" : "resource",
"classes" : [ "ResearchField" ],
"created_at" : "2023-10-06T11:28:14.613254+01:00",
"created_by" : "00000000-0000-0000-0000-000000000000",
"extraction_method" : "UNKNOWN",
"featured" : false,
"formatted_label" : null,
"id" : "subfield",
"label" : "Default Label",
"modifiable" : true,
"observatory_id" : "00000000-0000-0000-0000-000000000000",
"organization_id" : "00000000-0000-0000-0000-000000000000",
"shared" : 0,
"unlisted" : false,
"verified" : false
}
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : "INSTANCE",
"size" : 1,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Path | Type | Description |
---|---|---|
|
|
The ids of the parent research fields. |
|
|
Resource representation of the research field resource. |
Listing statistics about a research field
A GET
request lists statistics about a research field. Optionally accounts for subfields.
Curl request
$ curl 'https://incubating.orkg.org/api/stats/research-fields/R1?includeSubfields=false' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 71
{
"comparisons" : 5,
"id" : "R1",
"papers" : 25,
"total" : 30
}
Datasets & Benchmarks
Some datasets and benchmarks on said datasets are imported into the ORKG. Certain statistics can be obtained through the benchmark endpoint of the rest API.
Listing research fields with benchmarks
A GET
request lists all the research fields with benchmarks (i.e., all research fields that have papers containing benchmarks in their contributions).
Curl request
$ curl 'http://localhost:8080/api/research-fields/benchmarks' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 522
{
"content" : [ {
"id" : "R80",
"label" : "Field 1"
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 1,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 1,
"totalPages" : 1
}
Listing Benchmarks by Field
A GET
request lists benchmarks under a certain research field.
Curl request
$ curl 'http://localhost:8080/api/benchmarks/summary/research-field/R98?sort=problem.id,ASC' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 991
{
"content" : [ {
"research_fields" : [ {
"id" : "R98",
"label" : "Field with a dataset"
} ],
"research_problem" : {
"id" : "R104",
"label" : "Problem 1"
},
"total_codes" : 5,
"total_datasets" : 2,
"total_papers" : 1
}, {
"research_fields" : [ {
"id" : "R98",
"label" : "Field with a dataset"
} ],
"research_problem" : {
"id" : "R105",
"label" : "Problem 2"
},
"total_codes" : 5,
"total_datasets" : 2,
"total_papers" : 1
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"totalElements" : 2,
"totalPages" : 1
}
Benchmark Summary
A GET
request lists the datasets for a research problem (a.k.a. Benchmark Summary)
Curl request
$ curl 'http://localhost:8080/api/datasets/research-problem/R67?sort=totalModels,DESC' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 719
{
"content" : [ {
"id" : "R78",
"label" : "Dataset 1",
"total_codes" : 0,
"total_models" : 4,
"total_papers" : 1
}, {
"id" : "R79",
"label" : "Dataset 2",
"total_codes" : 3,
"total_models" : 0,
"total_papers" : 1
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"totalElements" : 2,
"totalPages" : 1
}
Benchmark Unpacked
A GET
request lists summary for a dataset (a.k.a. Benchmark unpacked).
Curl request
$ curl 'http://localhost:8080/api/datasets/R49/problem/R50/summary' -i -X GET \
-H 'Content-Type: application/json;charset=utf-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1111
{
"content" : [ {
"code_urls" : [ "https://some-code-3.cool", "https://some-code-2.cool", "https://some-code-1.cool" ],
"metric" : "Metric 2",
"model_id" : "R57",
"model_name" : "Model 1",
"paper_id" : "R52",
"paper_month" : null,
"paper_title" : "paper",
"paper_year" : null,
"score" : "4548"
}, {
"code_urls" : [ "https://some-code-3.cool", "https://some-code-2.cool", "https://some-code-1.cool" ],
"metric" : "Metric 1",
"model_id" : "R57",
"model_name" : "Model 1",
"paper_id" : "R52",
"paper_month" : null,
"paper_title" : "paper",
"paper_year" : null,
"score" : "2.55"
} ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 2,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 20,
"paged" : true,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"unpaged" : false
},
"size" : 20,
"sort" : {
"empty" : true,
"sorted" : false,
"unsorted" : true
},
"totalElements" : 2,
"totalPages" : 1
}
Reproducibility Score
The reproducibility score measures the availability, accessibility, linkability, and license of a resource.
License
License information of external code repositories can be obtained through the orkg to compute a reproducibility score for a resource.
The endpoint currently only supports GitHub repository URIs. |
Curl request
$ curl 'https://incubating.orkg.org/api/licenses?uri=https://github.com/github/docs' -i -X GET \
-H 'Content-Type: application/vnd.orkg.license.v1+json;charset=UTF-8' \
-H 'Accept: application/vnd.orkg.license.v1+json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/vnd.orkg.license.v1+json
Content-Length: 29
{
"license" : "CC-BY-4.0"
}
ORKG Widget
This API is intended for internal use of the ORKG widget, and not meant to be consumed by clients. It is documented here for completeness. Client authors can ignore it. |
The widget can obtain information via a GET
request to /api/widgets/
by providing one of the request parameters.
All request parameters are mutually exclusive.
Providing none or more than one will respond with status code 400 (Bad Request).
Curl request
$ curl 'https://incubating.orkg.org/api/widgets/?doi=10.1000/182' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Request parameters
Parameter | Description |
---|---|
|
The DOI of the resource to search. |
|
The title of the resource to search. |
Response fields
Path | Type | Description |
---|---|---|
|
|
The identifier of the resource. |
|
|
The DOI of the resource. May be |
|
|
The title of the resource. |
|
|
The class of the resource. Always one of |
|
|
The number of statements connected to the resource if the class is |
Statistics
Statistics are a way to obtain valuable information about the state of the graph. Every data point is provided by a predefined metric, which are organized in groups.
Listing groups
A GET
request provides a list of all available metric groups.
Curl request
$ curl 'https://incubating.orkg.org/api/statistics/' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the group. |
|
|
The URI of the group, which can be used to fetch a list of available metrics that are associated with this group. |
Listing metrics of a group
A GET
request provides a list of all available metrics of a given group.
Curl request
$ curl 'https://incubating.orkg.org/api/statistics/group1' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the metric. |
|
|
The URI of the metric, which can be used to fetch information about the metric and its current value. |
Fetching a metric
A GET
request provides information about a given metric within a group.
Curl request
$ curl 'https://incubating.orkg.org/api/statistics/group1/metric1' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 109
{
"description" : "Description of the metric.",
"group" : "group1",
"name" : "metric1",
"value" : 1
}
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the metric. |
|
|
The description of the metric. |
|
|
The group of the metric. |
|
|
The value of the metric. |
Identifiers
This section lists the supported identifiers for content-type endpoints.
Document identifiers
Name | Key | Predicate ID |
---|---|---|
DOI |
doi |
P26 |
Author identifiers
Name | Key | Predicate ID |
---|---|---|
ORCID |
orcid |
HAS_ORCID |
Google Scholar author ID |
google_scholar |
googleScholarID |
Research Gate profile ID |
research_gate |
researchGateID |
LinkedIn personal profile ID |
linked_in |
linkedInID |
Wikidata Identifier |
wikidata |
P76020 |
Web of Science ID |
web_of_science |
P58083 |
Visibility filter
Most content types support visibility filtering.
The filtering is supported in GET
requests via the "visibility" request parameter:
Request parameters
Parameter | Description |
---|---|
|
The visibility modifier. Must be one of |
Visibility filtering (obsolete)
To be backwards compatible, some endpoints support visibility filtering via additional request parameters in addition to the visibility
request parameter.
If the visibilty
request parameter is used, both featured
and unlisted
are ignored.
If it is absent, it will be set according to the values of the two parameters.
The use of these request parameters is deprecated and may be removed at some point. Clients are encouraged to transition to using the mechanism described in Visibility filter. |
Request parameters
Parameter | Description |
---|---|
|
Return only featured results. Defaults to |
|
Return only unlisted results. Defaults to |
Filter Configs
A filter config is an url-encoded json-list of search filters. They can be used to make advanced search queries on papers, providing a way for users to find the papers they are actually interested in. Each search filter is of the following structure:
{
"exact" : true,
"path" : [ "P105059", "P60013" ],
"range" : "Pattern",
"values" : [ {
"op" : "EQ",
"value" : "some value"
} ]
}
Path | Type | Description |
---|---|---|
|
|
Describes the path from the contribution node of a paper to the node that should be matched, where every entry stands for the predicate id of a statement. For example the path provided in the example above matches node n in the following graph: (:Paper)-[P31]→(:Contribution)-[P105059]→(:Thing)-[P60013]→(n:Thing) |
|
|
The class id that represents the range of the value that should be matched. Subclasses will also be considered when matching. |
|
|
A list that contains the actual values that should be matched. Multiple entries are logically combined with an OR operation, while multiple filter configs are logically combined with an AND operation. |
|
|
The logical matching operation. |
|
|
The value that needs to match. |
|
|
Whether to exactly match the given path. If |
Opcode | Operation |
---|---|
EQ |
Equals |
NE |
Not equals |
LT |
Less than |
LE |
Less or equal than |
GE |
Greater than |
GT |
Greater or equal than |
Sorting and Pagination
For all request that lists entities, pagination and sorting are applied automatically. The attributes of paged responses are described in the section about Page representations.
Endpoints supporting paging all take the following (optional) request parameters:
Parameter | Description |
---|---|
|
The page number requested, 0-indexed. |
|
The number of elements per page. May be lowered if it exceeds the limit. |
|
A string in the form "{property},{direction}". Sortable properties are dependent on the endpoint. Direction can be "asc" or "desc". Parameter can be repeated multiple times. The sorting is order-dependent. |
An example of a response of a paged list looks like this:
{
"content" : [ "bar", "baz", "foo" ],
"empty" : false,
"first" : true,
"last" : true,
"number" : 0,
"numberOfElements" : 3,
"pageable" : {
"offset" : 0,
"pageNumber" : 0,
"pageSize" : 10,
"paged" : true,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"unpaged" : false
},
"size" : 10,
"sort" : {
"empty" : false,
"sorted" : true,
"unsorted" : false
},
"totalElements" : 3,
"totalPages" : 1
}
The elements in content can be objects of arbitrary structure and are sorted according to the request parameters, if the endpoint supports it.
|
By default, sorting is done by the created_at
property (time-based).
Key | Description |
---|---|
For sorting resources |
|
id |
The id of the resource |
label |
The label of the resource |
created_at |
The datetime timestamp of the creation |
created_by |
The id of the curator who originally created the resource |
visibility |
The visibility of the resource |
For sorting predicates, classes & literals |
|
id |
The id of the predicate, class or literal |
label |
The label of the predicate, class or literal |
created_at |
The datetime timestamp of the creation |
created_by |
The id of the curator who originally created the predicate, class or literal |
For sorting statements |
|
id |
The statement id |
index |
The index of the statement |
created_at |
The datetime timestamp of the creation |
created_by |
The id of the curator who originally created the statement |
sub.id |
The id of the subject |
sub.label |
The label of the subject |
sub.created_at |
The creation timestamp of the subject |
sub.created_by |
The id of the curator who originally created the subject of the statement |
obj.id |
The id of the object |
obj.label |
The label of the object |
obj.created_at |
The creation timestamp of the object |
obj.created_by |
The id of the curator who originally created the object of the statement |
Representations
This section contains the resource definitions (also called representations) of the entities of this API.
Basic Types
Timestamps
All timestamps used in this API are in ISO 8601 format. Although nanosecond precision is available currently, clients MUST NOT rely on it, as it might be subject to change.
Errors
Path | Type | Description |
---|---|---|
|
|
The HTTP status code of the error. This is equal to the status code of the request itself and MUST only be used for display purposes. |
|
|
The human-readable error description of the status code, e.g. "Bad Request" for code 400. |
|
|
A human-readable, and hopefully helpful message that explains the error. |
|
|
The path to which the request was made that caused the error. |
|
|
The timestamp of when the error happened. |
Pages
Path | Type | Description |
---|---|---|
|
|
The result of the request as a (sorted) array. |
|
|
Determines if the current page is empty. |
|
|
Determines if the current page is the first one. |
|
|
Determines if the current page is the last one. |
|
|
The number of the current page. |
|
|
The number of elements currently on this page. |
|
|
The size of the current page. |
|
|
The sorting parameters for this page. |
|
|
Determines if the sort object is empty. |
|
|
Determines if the page is sorted. Inverse of |
|
|
Determines if the page is unsorted. Inverse of |
|
|
The total amounts of elements. |
|
|
The number of total pages. |
Entities
Resource
Path | Type | Description |
---|---|---|
|
|
The identifier of the resource. |
|
|
The label of the resource. It is intended to be read by humans and should be used for displaying the resource. |
|
|
The set of classes of which this resources is an instance of. |
|
|
The number of statements that have this resource in their object position. |
|
|
Determine if the resource is featured. Defaults to |
|
|
Determine if the resource is unlisted. Defaults to |
|
|
Determine if the resource is verified. Defaults to |
|
|
Determines how the resource was created. Can be one of |
|
|
The UUID of the observatory to which this resource belongs. |
|
|
The UUID of the organization to which this resource belongs. |
|
|
The timestamp when the resource was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this resource. |
|
|
Whether this resource can be modified. |
|
|
An indicator which type of entity was returned. Always has the value |
Literal
Path | Type | Description |
---|---|---|
|
|
The identifier of the literal. |
|
|
The literal value. |
|
|
The datatype of the literal. Can be a (prefixed) URI. |
|
|
The timestamp when the literal was created. (Also see JavaDoc). |
|
|
The UUID of the user or service who created this literal. |
|
|
Whether this literal can be modified. |
|
|
An indicator which type of entity was returned. Always has the value “literal”. |