API Documentation
Overview ¶
This document provides a complete reference to the REST API.
Graph URI ¶
Lets consider the following call: GET /api/{graphUri}/{conceptUri}.
When we are in a model, the {graphUri} is model:ModelId, like in the example operation Get concept scheme list.
When we are in a task, the {graphUri} is task:ModelId:TaskId, like in the example operation Delete an empty Concept Scheme.
IRI Escaping Rules ¶
Every time you construct URL for the API call, one or more IRIs are included in the URL. The IRIs must be properly escaped and encoded.
Compact vs Full IRIs
-
You can use either a full IRI or a prefixed form that uses JSON/LD
@contextto resolve it to full IRI, as defined in JSON/LD Specification. Prefixed form is a compact IRI represented as a prefix:suffix combination. The prefix matches a term defined within the active context and the suffix does not begin with two slashes (//). The compact IRI is expanded by concatenating the IRI mapped to the prefix to the (possibly empty) suffix. If the prefix is not defined in the active context, or the suffix begins with two slashes (such as in http://example.com), the value is interpreted as absolute IRI instead. If the prefix is an underscore (_), the value is interpreted as blank node identifier instead. -
The set of prefixes used to resolve the prefixed forms is taken from JSON/LD
@contextpassed usingLinkHTTP header or directly in body payload (later applies to POST requests only), as specified in JSON-LD - The Context
Escaping Rules
-
For both full and prefixed forms used in the URL of REST api calls the escaping rules are the same as in SPARQL, as documented in Syntax for IRIs. Notice the compact (prefixed) form requires additional escaping of some special characters (
~.-!$&'()*+,;=/?#@%) with\, as shown in example 2. -
In some cases SPARQL property paths are supported. The path can be a compound expression containing more than one IRI, as specified in SPARQL - Property Paths
-
After escaping the IRI must by url-encoded before being placed in the URL, as per RFC3986
-
There are limitations of some proxies (eg Semaphore cloud) that blocks passing some IRIs even if they are properly encoded. Special characters like
/\:.which might be involved in path calculation by web server/proxy are often blocked. Alternative way of passing IRIs in URL is http query level parameterpath. Passing values as parameters requires additional http standard escaping as per RFC3986. So the special characters are double encoded in such case. The workbench frontend uses this way by default as it is the safest. -
Path fields in JSON-PATCH requests requires additional IRIs preprocessing. See JSON-PATCH
Examples
Lets consider we want to retrieve resource with given IRI using REST API call.
Example 1
- Full IRI:
http://proto.smartlogic.com/example#Topics
Can be represented as prefixed form with default context:
-
In JSON-LD payload:
example:Topics -
As SPARQL resource:
example:Topics -
REST API URL:
GET /api/model%3AmyExample/example%3ATopics -
Proxy-safe REST API URL:
GET /api?path=model%253AmyExample%2Fexample%253ATopics
Or, can be represented as full IRI:
-
In JSON-LD payload:
http://proto.smartlogic.com/example#Topics -
As SPARQL resource:
<http://proto.smartlogic.com/example#Topics> -
REST API URL:
GET /api/model%3AmyExample/%3Chttp%3A%2F%2Fproto.smartlogic.com%2Fexample%23Topics%3E -
Proxy-safe REST API URL:
GET /api?path=model%253AmyExample%2F%253Chttp%253A%252F%252Fproto.smartlogic.com%252Fexample%2523Topics%253E
Example 2 ( with special character )
- Full IRI:
http://proto.smartlogic.com/example#Topics~2
Can be represented as prefixed form with default context:
-
In JSON-LD payload:
example:Topics~2 -
As SPARQL resource:
example:Topics\~2 -
REST API URL:
GET /api/model%3AmyExample/example%3ATopics%5C~2 -
Proxy-safe REST API URL:
GET /api?path=model%253AmyExample%2Fexample%253ATopics%255C~2
Or, can be represented as full IRI:
-
In JSON-LD payload:
http://proto.smartlogic.com/example#Topics~2 -
As SPARQL resource:
<http://proto.smartlogic.com/example#Topics~2> -
REST API URL:
GET /api/model%3AmyExample/%3Chttp%3A%2F%2Fproto.smartlogic.com%2Fexample%23Topics~2%3E -
Proxy-safe REST API URL:
GET /api?path=model%253AmyExample%2F%253Chttp%253A%252F%252Fproto.smartlogic.com%252Fexample%2523Topics~2%253E
Payload Formats ¶
Every time you issue a HTTP request the request and/or response will have a payload with specific content type. This section describes the content types used in Semaphore Workbench API.
The Rules
Graph related API
-
GET calls:
- request: no payload
- response: JSON-LD
-
POST calls:
- request: JSON-LD
- response:
- no payload, unless errors/warnings were detected
- JSON payload, if errors/warnings were detected, see Error Handling
-
PATCH calls:
- request: JSON-PATCH
- response:
- no payload, unless errors/warnings were detected
- JSON payload, if errors/warnings were detected, see Error Handling
-
DELETE calls:
- request: no payload
- response:
- no payload, unless errors/warnings were detected
- JSON payload, if errors/warnings were detected, see Error Handling
Auxiliary (non-graph related) API
-
GET calls, non-graph related:
- request: no payload
- response: JSON
-
POST calls, non-graph related:
- request: JSON
- response: JSON
Formats
Generally all payloads are 100% JSON compatible. In addition to generic JSON we also use JSON-LD (JSON-based lightweight Linked Data format for representing any RDF models) and JSON Patch (JSON-based notation to express a sequence of operations on a JSON document).
JSON
-
Content-Type:
application/json -
Webpage: http://www.json.org/
-
Standard: https://tools.ietf.org/html/rfc7159
Simple auxiliary calls with use a generic call-specific JSON payloads. Also all JSON-LD and JSON-Patch payloads are fully JSON compatible, so can be produced and/or parsed with generic json libraries.
JSON Example
If we send a GET http://workbench.example.com/api/special/backend request with no payload, the server will response with json payload:
{
"current": "TDB"
}JSON-LD
-
Content-Type:
application/ld+json -
Webpage: http://json-ld.org/
-
Standard: https://www.w3.org/TR/json-ld/
All graph related GET and POST calls use this format to represent an arbitrary graph, or a set of graphs.
JSON-LD Example
If we send a GET http://workbench.example.com/api/model:myExample/example:Topics?properties=... request with no payload, the server will response with json-ld payload:
{
"@graph": [
{
"@id": "example:Topics",
"@type": ["skos:ConceptScheme"],
"rdfs:label": [
{
"@value": "Topics",
"@language": "en"
}
],
"skos:hasTopConcept": [
{"@id": "example:Ethics"},
{"@id": "example:FinanceAndEconomics"},
{"@id": "example:Labour"},
{"@id": "example:LawAndRegulation"}
]
}
]
}JSON-PATCH
-
Content-Type:
application/json-patch+json -
Webpage: http://jsonpatch.com/
-
Standard: http://tools.ietf.org/html/rfc6902
Our PATCH method implementation uses this content type to allow clients to represent any sequence of changes to apply to a graph, represented by a JSON document using JSON-LD notation.
The semantics of HTTP PATCH operation is that it represents operations on a “virtual” JSON document that you would receive if you issue a GET call with the same URL. The underlying implementation does not, in fact, materialise such a JSON document, but instead applies the operations represented by the JSON-Patch directly to the RDF model stored as a graph in the database.
Since the JSON-Patch specification can be used to represent changes to an arbitrary JSON document, some extra rules are required to disambiguate the JSON-Patch operations. The ambiguity stems from the fact that while arrays in JSON document are ordered sequences, the same is not true for JSON-LD representation of RDF models. Because RDF models are unordered collections of triples, the resulting arrays in JSON-LD representation have an arbitrary order of elements. Therefore, in order to disambiguate the JSON-Patch paths that contain array indices, some extra “test” operations must be included in JSON-Patch payload.
These “test” operations effectively binds the index from the “path” to the specific value. For example, the following test operation:
{
"op": "test",
"path": "@graph/0/skos:hasTopConcept/2",
"value": {"@id": "example:Labour"}
}Expresses the fact that the “path” above addresses the element in skos:hasTopConcept array,
that has value example:Labour. The actual index value (2) is arbitrary - all that matters is
that the same index is not reused in the same PATCH request to refer to some other element.
Warning
If you need to refer to a key with ‘~’ or ‘/’ in its name, you must escape the characters with ‘~0’ and ‘~1’ respectively. See “JSON Pointer” section in http://jsonpatch.com/ for more information and JSON-PATCH Example: Adding element to array using full URI.
Examples
For the purpose of examples below we assume the example:Topics concept scheme is represented by
the JSON-LD documented as in previous section -
JSON-LD Example.
JSON-PATCH Example: Adding element to array
In this PATCH request we are executing a JSON-Patch “add” operation that adds a single
element example:Computers to a skos:hasTopConcept array of example:Topics object.
Notice we use “-” as an array index, which means “at the end of the array” in JSON-Patch specification, but we could have also used any other index, since JSON-LD arrays are not ordered.
We need to send PATCH http://workbench.example.com/api/model:myExample/example:Topics request with json-patch payload:
[
{
"op": "add",
"path": "@graph/0/skos:hasTopConcept/-",
"value": {"@id": "example:Computers"}
}
]JSON-PATCH Example: Adding element to array using full URI
In this PATCH request we are doing the same as in previous one, except we are using full URI for skos:hasTopConcept, that is http://www.w3.org/2004/02/skos/core#hasTopConcept. In this case we have to change ‘/’ for ‘~1’ in URI.
We need to send PATCH http://workbench.example.com/api/model:myExample/example:Topics request with json-patch payload:
[
{
"op": "add",
"path": "@graph/0/http:~1~1www.w3.org~1~12004~1~102~1~1skos~1~1core#hasTopConcept/-",
"value": {"@id": "example:Computers"}
}
]JSON-PATCH Example: Removing element from array
In this PATCH request we are executing a JSON-Patch “remove” operation that removes a single
element with index 2 from skos:hasTopConcept array of example:Topics object. This element
is addressed by @graph/0/skos:hasTopConcept/2 path.
Notice that such “remove” operation must be preceded by a test operations that binds this path
to an element example:Labour. Otherwise such path would be ambiguous (because of an arbitrary
ordering of JSON-LD arrays it is non-deterministic which element has index 2) and such a PATCH
request would result in an error.
Also notice that the first “0” in the same path does not need disambiguation, since from the request
URL we know that this query operates on a single model “myExample”, to which the @graph/0 part of
the path refers.
We need to send PATCH http://workbench.example.com/api/model:myExample/example:Topics request with json-patch payload:
[
{
"op": "test",
"path": "@graph/0/skos:hasTopConcept/2",
"value": {"@id": "example:Labour"}
},
{
"op": "remove",
"path": "@graph/0/skos:hasTopConcept/2"
}
]JSON-PATCH Example: Replacing element in array
In this PATCH request we are executing a JSON-Patch “replace” operation that replaces element with
index 2 of skos:hasTopConcept array of example:Topics with example:Computers. This
element is addressed by @graph/0/skos:hasTopConcept/2 path.
Notice that such “replace” operation must be preceded by a test operations that binds this path
to an element example:Labour. Otherwise such path would be ambiguous (because of an arbitrary
ordering of JSON-LD arrays it is non-deterministic which element has index 2) and such a PATCH
request would result in an error.
Also notice that the first “0” in the same path does not need disambiguation, since from the request
URL we know that this query operates on a single model model:myExample, to which the @graph/0
part of the path refers.
We need to send PATCH http://workbench.example.com/api/model:myExample/example:Topics request with json-patch payload:
[
{
"op": "test",
"path": "@graph/0/skos:hasTopConcept/2",
"value": {"@id": "example:Labour"}
},
{
"op": "replace",
"path": "@graph/0/skos:hasTopConcept/2",
"value": {"@id": "example:Computers"}
}
]Basic Operations ¶
Basic CRUD operations on Concept and ConceptSchemes. Also included are are basic search queries, such as getting list of all concept schemes or finding narrower/broader/related concepts.
Basic Operations - Concept Schemes ¶
All Concept Schemes ¶
Get concept scheme listGET/{graphUri}/skos:ConceptScheme/rdf:instance{?properties}
Example URI
GET /model:myExample/skos:ConceptScheme/rdf:instance?properties=meta:meta/skos:hasTopConcept/meta:exist
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: meta:meta/skos:hasTopConcept/meta:exist
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [{
"@id": "example:Brands",
"meta:meta": {
"@id": "_:NNN",
"skos:hasTopConcept": {
"@id": "_:NNN",
"meta:exist": true
}
}
}, {
"@id": "example:Companies",
"meta:meta": {
"@id": "_:NNN",
"skos:hasTopConcept": {
"@id": "_:NNN",
"meta:exist": true
}
}
}, {
"@id": "example:ExecutiveManagement",
"meta:meta": {
"@id": "_:NNN",
"skos:hasTopConcept": {
"@id": "_:NNN",
"meta:exist": true
}
}
}, {
"@id": "example:IndustrySector",
"meta:meta": {
"@id": "_:NNN",
"skos:hasTopConcept": {
"@id": "_:NNN",
"meta:exist": true
}
}
}, {
"@id": "example:Topics",
"meta:meta": {
"@id": "_:NNN",
"skos:hasTopConcept": {
"@id": "_:NNN",
"meta:exist": true
}
}
}]
}Create new ConceptScheme with given URIPOST/{graphUri}/skos:ConceptScheme/rdf:instance
Example URI
POST /model:myExample/skos:ConceptScheme/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:ConceptScheme4",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "ABC"
}Response
201Headers
Location: ../example:ConceptScheme4
X-Location-Uri: example:ConceptScheme4Create new ConceptScheme with auto-generated URIPOST/{graphUri}/skos:ConceptScheme/rdf:instance
Example URI
POST /model:myExample/skos:ConceptScheme/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "ConceptSchemeNameForUriGeneration"
}Response
201Headers
Location: ../%3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FConceptScheme%2FConceptSchemeNameForUriGeneration%3E
x-location-uri: %3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FConceptScheme%2FConceptSchemeNameForUriGeneration%3ESingle Concept Scheme ¶
Get label and topConcepts of concept schemeGET/{graphUri}/{conceptSchemeUri}{?properties}
Example URI
GET /model:myExample/example:Topics?properties=rdfs:label,skos:hasTopConcept/(meta:displayName|meta:meta/skos:narrower/meta:exist)
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptSchemeUri
string(required) Example: example:Topics- properties
string(optional) Example: rdfs:label,skos:hasTopConcept/(meta:displayName|meta:meta/skos:narrower/meta:exist)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:Topics",
"rdfs:label":
[{
"@language": "en",
"@value": "Topics"
}],
"skos:hasTopConcept":
[
{
"@id": "example:Ethics",
"meta:displayName":
{
"@language": "en",
"@value": "Ethics"
},
"meta:meta":
{
"@id": "_:NNN",
"skos:narrower":{
"@id": "_:NNN",
"meta:exist": true
}
}
},
{
"@id": "example:FinanceAndEconomics",
"meta:displayName":
{
"@language": "en",
"@value": "Finance & economics"
},
"meta:meta":
{
"@id": "_:NNN",
"skos:narrower":{
"@id": "_:NNN",
"meta:exist": true
}
}
},
{
"@id": "example:Labour",
"meta:displayName":
{
"@language": "en",
"@value": "Labour"
},
"meta:meta":
{
"@id": "_:NNN",
"skos:narrower": {
"@id": "_:NNN",
"meta:exist": true
}
}
},
{
"@id": "example:LawAndRegulation",
"meta:displayName":
{
"@language": "en",
"@value": "Law & regulation"
},
"meta:meta":
{
"@id": "_:NNN",
"skos:narrower": {
"@id": "_:NNN",
"meta:exist": true
}
}
}
]
}
]
}Add label using POSTPOST/{graphUri}/{conceptSchemeUri}
Example URI
POST /model:myExample/example:Topics
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptSchemeUri
string(required) Example: example:Topics
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Countries",
"rdfs:label": {
"@value": "Kraje",
"@language": "pl"
}
}Response
200Add a labelPATCH/{graphUri}/{conceptSchemeUri}
Example URI
PATCH /model:myExample/example:Topics
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptSchemeUri
string(required) Example: example:Topics
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/rdfs:label/-",
"value": {
"@value": "Topics2",
"@language": "pl"
}
}
]Response
200Remove a labelPATCH/{graphUri}/{conceptSchemeUri}
Example URI
PATCH /model:myExample/example:Topics
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptSchemeUri
string(required) Example: example:Topics
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "en"
}
},
{
"op": "remove",
"path": "@graph/0/rdfs:label/0"
}
]Response
200Replace a labelPATCH/{graphUri}/{conceptSchemeUri}
Example URI
PATCH /model:myExample/example:Topics
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptSchemeUri
string(required) Example: example:Topics
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics2",
"@language": "en"
}
}
]Response
200Delete an empty Concept SchemeDELETE/{graphUri}/{conceptSchemeUri}{?mode}
Example URI
DELETE /task:myExample:test/example:EmptyScheme?mode=empty
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptSchemeUri
string(required) Example: example:EmptyScheme- mode
string(required) Example: empty
Response
200Delete Concept Scheme and re-attach childrenDELETE/{graphUri}/{conceptSchemeUri}{?mode,newParent}
Example URI
DELETE /task:myExample:test/example:Polish_Cities?mode=reattach&newParent=example:Cities
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptSchemeUri
string(required) Example: example:Polish_Cities- mode
string(required) Example: reattach- newParent
string(required) Example: example:Cities
Response
200Basic Operations - Concepts ¶
All Concepts ¶
Get concepts listGET/{graphUri}/skos:Concept/meta:transitiveInstance{?properties,limit}
Example URI
GET /model:myExample/skos:Concept/meta:transitiveInstance?properties=rdf:type&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: rdf:type- limit
string(required) Example: 100
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:AstraZenecaPLC",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:BritishAirwaysPLC",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:DavidBrennan",
"@type" : [ "example:Executive" ]
}, {
"@id" : "example:Diprivan",
"@type" : [ "example:Brand" ]
}, {
"@id" : "example:IPRPharmaceuticalsInc",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:Losec",
"@type" : [ "example:Brand" ]
}, {
"@id" : "example:Nexium",
"@type" : [ "example:Brand" ]
}, {
"@id" : "example:NextPLC",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:Orange",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:Pulmicort",
"@type" : [ "example:Brand" ]
}, {
"@id" : "example:Semaphore",
"@type" : [ "example:Brand" ]
}, {
"@id" : "example:SmartlogicLtd",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:TerrenceLeahy",
"@type" : [ "example:Executive" ]
}, {
"@id" : "example:TescoPLC",
"@type" : [ "example:Company" ]
}, {
"@id" : "example:WilliamWalsh",
"@type" : [ "example:Executive" ]
}, {
"@id" : "example:Airlines",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:BankingSupervision",
"@type" : [ "example:ConsumerProtection", "example:LegalAndRegulatory" ]
}, {
"@id" : "example:ChildLabour",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:ClothingRetail",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:CommodityPrices",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:Compliance",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:ConsumerDiscretionary",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:ConsumerStaples",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:CorporateSocialResponsibility",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:DataProtection",
"@type" : [ "example:Privacy", "example:Technology" ]
}, {
"@id" : "example:Ethics",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:FinanceAndEconomics",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:FoodAndStaplesRetailing",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:FoodRetail",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:HealthCare",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:Labour",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:LabourConditions",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:LawAndRegulation",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:MedicalNegligence",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:Negligence",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:OilPrices",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:Patents",
"@type" : [ "example:Topic" ]
}, {
"@id" : "example:Pharmaceuticals",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:PharmaceuticalsAndBiotechnology",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:Retailing",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:Telecommunications",
"@type" : [ "example:Sector" ]
}, {
"@id" : "example:Transportation",
"@type" : [ "example:Sector" ]
} ]
}Create a concept that is a child of a concept schemePOST/{graphUri}/skos:Concept/rdf:instance
Example URI
POST /model:myExample/skos:Concept/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Drinks",
"@type": [
"skos:Concept"
],
"skos:topConceptOf": {
"@id": "example:Topics"
},
"skosxl:prefLabel": [
{
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks",
"@language": "en"
}
]
}
]
}Response
201Headers
x-location-uri: example:DrinksCreate multiple concepts that are children of another conceptPOST/{graphUri}/skos:Concept/rdf:instance
Example URI
POST /model:myExample/skos:Concept/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@graph": [
{
"@id": "example:OntologyServer",
"@type": [
"skos:Concept"
],
"skos:broader": {
"@id": "example:Semaphore"
},
"skosxl:prefLabel": {
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": {
"@value": "Ontology Server",
"@language": "en"
}
}
},
{
"@id": "example:Publisher",
"@type": [
"skos:Concept"
],
"skos:broader": {
"@id": "example:Semaphore"
},
"skosxl:prefLabel": {
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": {
"@value": "Publisher",
"@language": "en"
}
}
}
]
}Response
201Create a concept with a typePOST/{graphUri}/skos:Concept/rdf:instance
Example URI
POST /model:myExample/skos:Concept/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Warsaw",
"@type": [
"example:City",
"skos:Concept"
],
"skos:topConceptOf": {
"@id": "example:Cities"
},
"skosxl:prefLabel": [
{
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks",
"@language": "en"
}
]
}
]
}Response
201Single Concept ¶
Get concept with all the detailsGET/{graphUri}/{conceptUri}{?properties}
Example URI
GET /model:myExample/example:Ethics?properties=[]
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Ethics- properties
string(optional) Example: []
Response
200Headers
Content-Type: application/ld+json
x-do-not-retry: trueBody
{
"@context": {...},
"@graph": [
{
"@id": "example:Ethics",
"@type": ["example:Topic"],
"skos:narrower" : [ {
"@id": "example:CorporateSocialResponsibility"
}, {
"@id": "example:LabourConditions"
} ],
"skos:topConceptOf" : [ {
"@id": "example:Topics"
} ],
"skosxl:prefLabel": [
{
"@id": "example:Ethics_en"
}, {
"@id" : "example:Ethics_fr"
}
],
"sem:guid": [ { "@value": "AAAA0000-AA00-AA00-AA00-AAAAAA000000" }]
}
]
}Get concept with prefLabelsGET/{graphUri}/{conceptUri}{?properties}
Example URI
GET /model:myExample/example:Airlines?properties=skosxl:prefLabel/skosxl:literalForm
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Airlines- properties
string(optional) Example: skosxl:prefLabel/skosxl:literalForm
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:Airlines",
"skosxl:prefLabel": [
{
"@id": "example:Airlines_en",
"skosxl:literalForm": [{
"@language": "en",
"@value": "Airlines"
}]
},
{
"@id": "example:Airlines_fr",
"skosxl:literalForm": [{
"@language": "fr",
"@value": "Compagnies aériennes"
}]
}
]
}
]
}Get concept with altLabelsGET/{graphUri}/{conceptUri}{?properties}
Example URI
GET /model:myExample/example:DavidBrennan?properties=skosxl:altLabel/skosxl:literalForm
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:DavidBrennan- properties
string(optional) Example: skosxl:altLabel/skosxl:literalForm
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:DavidBrennan",
"skosxl:altLabel": [
{
"@id": "example:BrennanDavidR_",
"skosxl:literalForm": [{
"@value": "Brennan, David R."
}]
},
{
"@id": "example:DavidRBrennan_",
"skosxl:literalForm": [{
"@value": "David R. Brennan"
}]
}
]
}
]
}Get concept with given metadata onlyGET/{graphUri}/{conceptUri}{?properties}
Example URI
GET /model:myExample/example:SmartlogicLtd?properties=skos:editorialNote
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:SmartlogicLtd- properties
string(optional) Example: skos:editorialNote
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:SmartlogicLtd",
"skos:editorialNote": [
{
"@value": "Record custodian is Rupert Bentley",
"@language": "en"
}
]
}
]
}Get narrower concepts each with flag if narrower existGET/{graphUri}/{conceptUri}{?properties}
Example URI
GET /model:myExample/example:Ethics?properties=rdf:type,skos:narrower/(rdf:type|meta:displayName|meta:meta/skos:narrower/meta:exist)
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Ethics- properties
string(optional) Example: rdf:type,skos:narrower/(rdf:type|meta:displayName|meta:meta/skos:narrower/meta:exist)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:Ethics",
"@type": ["example:Topic"],
"skos:narrower": [
{
"@id": "example:CorporateSocialResponsibility",
"@type": ["example:Topic"],
"meta:displayName": {
"@value": "Corporate Social Responsibility",
"@language": "en"
},
"meta:meta": {
"@id": "_:NNN",
"skos:narrower" : {
"@id": "_:NNN",
"meta:exist" : false
}
}
},
{
"@id": "example:LabourConditions",
"@type": ["example:Topic"],
"meta:displayName": {
"@value": "Labour conditions",
"@language": "en"
},
"meta:meta": {
"@id": "_:NNN",
"skos:narrower" : {
"@id": "_:NNN",
"meta:exist" : true
}
}
}
]
}
]
}Get narrower concepts each with flag if narrower existGET/{graphUri}/{conceptUri}{?properties,filters}
Example URI
GET /model:myExample/example:HealthCare?properties=rdf:type,?skosNarrower/(rdf:type|meta:displayName|meta:meta/?skosNarrower2/meta:exist)&filters=skosNarrower(rdfs:subPropertyOf*=skos:narrower),skosNarrower2(rdfs:subPropertyOf*=skos:narrower)
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:HealthCare- properties
string(optional) Example: rdf:type,?skosNarrower/(rdf:type|meta:displayName|meta:meta/?skosNarrower2/meta:exist)- filters
string(optional) Example: skosNarrower(rdfs:subPropertyOf*=skos:narrower),skosNarrower2(rdfs:subPropertyOf*=skos:narrower)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "example:HealthCare",
"@type": ["example:Sector"],
"skos:narrowMatch" : [ {
"@id" : "example:MedicalNegligence",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Medical negligence"
},
"meta:meta" : {
"@id": "_:NNN",
"semvar:skosNarrower2" : {
"@id": "_:NNN",
"meta:exist" : false
}
}
} ],
"skos:narrower": [
{
"@id": "example:PharmaceuticalsAndBiotechnology",
"@type": ["example:Sector"],
"meta:displayName": {
"@value": "Pharmaceuticals and biotechnology",
"@language": "en"
},
"meta:meta": {
"@id": "_:NNN",
"semvar:skosNarrower2" : {
"@id": "_:NNN",
"meta:exist" : true
}
}
}
]
}
]
}Add skos:editorialNote metadataPOST/{graphUri}/{conceptUri}
Example URI
POST /model:myExample/example:Warsaw
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Warsaw
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Warsaw",
"skos:editorialNote": "Capital of Poland"
}Response
200Headers
x-location-uri: example:Warsaw
x-do-not-retry: trueAdd concept classPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Warsaw
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Warsaw
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "/@graph/0/@type/-",
"value": "example:City"
}
]Response
200Add prefLabelPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Drinks
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Drinks
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/skosxl:prefLabel/-",
"value": {
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks DE",
"@language": "de"
}
]
}
}
]Response
200Add altLabel with idPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Drinks
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Drinks
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/skosxl:altLabel/-",
"value": {
"@id": "example:Label1",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks with"
}
]
}
}
]Response
200Add multiple metadataPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Warsaw
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Warsaw
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/skos:editorialNote/-",
"value": "Added by API test"
},
{
"op": "add",
"path": "@graph/0/example:issuedShareCapital/-",
"value": 1000000
},
{
"op": "add",
"path": "@graph/0/example:established/-",
"value": {
"@value": "2007-03-28",
"@type": "xsd:date"
}
}
]Response
200Add related conceptPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Poland
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Poland
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "/@graph/0/skos:related/-",
"value": {
"@id": "example:Warsaw"
}
}
]Response
200Add multiple new narrower conceptsPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Semaphore
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Semaphore
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "/@graph/0/skos:narrower/-",
"value": {
"@id": "example:OntologyServer",
"@type": [
"skos:Concept"
],
"skosxl:prefLabel": {
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Ontology Server",
"@language": "en"
}
]
}
}
},
{
"op": "add",
"path": "/@graph/0/skos:narrower/-",
"value": {
"@id": "example:Publisher",
"@type": [
"skos:Concept"
],
"skosxl:prefLabel": {
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Publisher",
"@language": "en"
}
]
}
}
}
]Response
200Remove concept classPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Warsaw
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Warsaw
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "/@graph/0/@type/0",
"value": "example:City"
},
{
"op": "remove",
"path": "/@graph/0/@type/0"
}
]Response
200Remove prefLabelPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Drinks
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Drinks
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skosxl:prefLabel/0",
"value": [
{
"@id": "example:TopicsLabel1",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks",
"@language": "en"
}
]
}
]
},
{
"op": "remove",
"path": "@graph/0/skosxl:prefLabel/0"
}
]Response
200Remove altLabelPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Drinks
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Drinks
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skosxl:altLabel/0",
"value": [
{
"@id": "example:TopicsLabel2",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "beverages",
"@language": "en"
}
]
}
]
},
{
"op": "remove",
"path": "@graph/0/skosxl:altLabel/0"
}
]Response
200Remove relationship to another conceptPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Poland
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Poland
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skos:related/0",
"value": [
{
"@id": "example:Warsaw"
}
]
},
{
"op": "remove",
"path": "@graph/0/skos:related/0"
}
]Response
200Replace existing altLabel, using remove+add operationsPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Drinks
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Drinks
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skosxl:altLabel/0",
"value": [
{
"@id": "example:TopicsLabel3",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": {
"@value": "Water",
"@language": "en"
}
}
]
},
{
"op": "remove",
"path": "@graph/0/skosxl:altLabel/0"
},
{
"op": "add",
"path": "@graph/0/skosxl:altLabel/0",
"value": {
"@id": "example:TopicsLabel3",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": {
"@value": "Updated water"
}
}
}
]Response
200Replace narrower conceptPATCH/{graphUri}/{conceptUri}
Example URI
PATCH /model:myExample/example:Semaphore
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptUri
string(required) Example: example:Semaphore
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "/@graph/0/skos:narrower/0",
"value": {
"@id": "example:OntologyManager"
}
},
{
"op": "replace",
"path": "/@graph/0/skos:narrower/0",
"value": {
"@id": "example:OntologyServer"
}
}
]Response
200Delete concept with no childrenDELETE/{graphUri}/{conceptUri}{?mode}
Example URI
DELETE /task:myExample:test/example:Warsaw?mode=empty
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptUri
string(required) Example: example:Warsaw- mode
string(required) Example: empty
Response
200Delete concept and re-attach children to its parentDELETE/{graphUri}/{conceptUri}{?mode}
Example URI
DELETE /task:myExample:test/example:Warsaw?mode=reattach
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptUri
string(required) Example: example:Warsaw- mode
string(optional) Example: reattach
Response
200Delete and drop subtreeDELETE/{graphUri}/{conceptUri}{?mode}
Example URI
DELETE /task:myExample:test/example:Warsaw?mode=withSubtree
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptUri
string(required) Example: example:Warsaw- mode
string(optional) Example: withSubtree
Response
200Single Label ¶
Replace literalForm of existing prefLabelPATCH/{graphUri}/{labelUri}
Example URI
PATCH /model:myExample/example:TopicsLabel1
URI Parameters
- graphUri
string(required) Example: model:myExample- labelUri
string(required) Example: example:TopicsLabel1
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skosxl:literalForm/0",
"value": {
"@value": "Drinks",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/skosxl:literalForm/0",
"value": {
"@value": "Updated Drinks",
"@language": "en"
}
}
]Response
200System Operations - Overview ¶
Basic CRUD operations on Models and Tasks.
System Operations - Models ¶
All Models ¶
Retrieve list of models with name names and commentsGET/specialgraph:system/teamwork:Tag/rdf:instance{?filters,properties}
Example URI
GET /specialgraph:system/teamwork:Tag/rdf:instance?filters=subject(rdfs:label matches "^myExample-test-")&properties=swa:defaultNamespace,rdfs:comment,dcterms:created,dcterms:language/(meta:displayName|skos:notation),semsys:lastModificationDate,semsys:lastModificationAuthor,meta:displayName,rdfs:label,meta:meta/(semsys:hasTask|meta:hasUser|semsys:imports)/meta:count,semsys:allows,semsys:graphUri,semsys:expandedGraphUri
URI Parameters
- properties
string(optional) Example: swa:defaultNamespace,rdfs:comment,dcterms:created,dcterms:language/(meta:displayName|skos:notation),semsys:lastModificationDate,semsys:lastModificationAuthor,meta:displayName,rdfs:label,meta:meta/(semsys:hasTask|meta:hasUser|semsys:imports)/meta:count,semsys:allows,semsys:graphUri,semsys:expandedGraphUri- filters
string(optional) Example: subject(rdfs:label matches "^myExample-test-")
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "model:myExample-test-1.tch",
"dcterms:created": [
{
"@type": "xsd:dateTime",
"@value": "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}
],
"dcterms:language": [
{
"@id": "lang:en",
"meta:displayName": {
"@language": "en",
"@value": "English"
},
"skos:notation": [
{
"@value": "en"
}
]
}
],
"swa:defaultNamespace": [
{
"@value": "http://example.org/test/"
}
],
"semsys:expandedGraphUri": [
{
"@value": "urn:x-evn-master:myExample-test-1"
}
],
"semsys:graphUri": [
{
"@id": "model:myExample-test-1"
}
],
"meta:displayName": {
"@value": "myExample-test-1"
},
"meta:meta": {
"@id": "_:NNN",
"semsys:imports": {
"@id": "_:NNN",
"meta:count": 1
},
"semsys:hasTask": {
"@id": "_:NNN",
"meta:count": 0
},
"meta:hasUser": {
"@id": "_:NNN",
"meta:count": 1
}
},
"semsys:lastModificationAuthor": [
{
"@id": "user:Administrator"
}
],
"semsys:lastModificationDate": [
{
"@type": "xsd:dateTime",
"@value": "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}
],
"semsys:allows": [
{"@id": "sempubpermissions:DownloadModelConfiguration"},
{"@id": "sempubpermissions:DownloadModelResults"},
{"@id": "sempermissions:AddComments"},
{"@id": "sempermissions:CanModifyModelStructure"},
{"@id": "sempermissions:CommitTasks"},
{"@id": "sempermissions:ConfigureORT"},
{"@id": "sempermissions:CreateTasks"},
{"@id": "sempermissions:Delete"},
{"@id": "sempermissions:DeleteChangeDetails"},
{"@id": "sempermissions:DeleteLiteralsInLanguage"},
{"@id": "sempermissions:DeleteNotOpenComments"},
{"@id": "sempermissions:DeleteOtherUsersComments"},
{"@id": "sempermissions:DeleteOwnComments"},
{"@id": "sempermissions:Edit"},
{"@id": "sempermissions:EditDefinition"},
{"@id": "sempermissions:ManageLanguages"},
{"@id": "sempermissions:ManageLinking"},
{"@id": "sempermissions:ModifyComments"},
{"@id": "sempermissions:UseReporting"},
{"@id": "sempermissions:View"}
],
"rdfs:comment": [
{
"@value": "Comment 1"
}
],
"rdfs:label": [
{
"@value": "myExample-test-1"
}
]
} ]
}Create Model ¶
Create new modelPOST/sys/sys:Model/rdf:instance
Example URI
POST /sys/sys:Model/rdf:instance
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"sys:Model"
],
"rdfs:label": [
{
"@value": "myExample-test-1"
}
],
"swa:defaultNamespace": [
{
"@value": "http://example.org/test/"
}
],
"rdfs:comment": {
"@value": "Comment 1"
}
}Response
201Headers
Location: ../model:myExample-test-1Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"sys:Model"
],
"rdfs:label": [
{
"@value": "myExample-test-2"
}
],
"swa:defaultNamespace": [
{
"@value": "http://example.org/test/"
}
],
"rdfs:comment": {
"@value": "Comment 2"
}
}Response
201Headers
Location: ../model:myExample-test-2Create new model with configured languagesPOST/sys/sys:Model/rdf:instance
Example URI
POST /sys/sys:Model/rdf:instance
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"sys:Model"
],
"rdfs:label": [
"myExample-test"
],
"swa:defaultNamespace": [
"http://example.org/test/"
],
"rdfs:comment": "Comment 1",
"dcterms:language": [
{
"@id": "lang:pl",
"dc:title": {
"@value": "Polish",
"@language": "en"
}
},
{
"@id": "lang:fr"
}
]
}Response
201Headers
Location: ../model:myExample-testCreate new model with configured user rolesPOST/sys/sys:Model/rdf:instance
Example URI
POST /sys/sys:Model/rdf:instance
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"sys:Model"
],
"rdfs:label": [
"myExample-test"
],
"swa:defaultNamespace": [
"http://example.org/test/"
],
"sempermissions:manager": [
{
"@id": "user:ApiTest-19.200655.908-User1"
}
],
"sempermissions:editor": [
{
"@id": "user:ApiTest-19.200655.908-User2"
}
],
"sempermissions:viewer": [
{
"@id": "role:SemaphoreUsers"
}
]
}Response
201Headers
Location: ../model:myExample-testSingle Model ¶
Get modelGET/sys/{graphUri}{?properties}
Example URI
GET /sys/model:myExample?properties=rdf:type,dcterms:created,semfun:graphLastModificationDate,sioc:has_creator,meta:graphUri,meta:displayName,meta:expandedUri,swa:defaultNamespace,rdfs:label,meta:meta/(meta:hasLinked|semfun:hasMainTag|meta:hasTerm|meta:hasUser)/meta:count
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: rdf:type,dcterms:created,semfun:graphLastModificationDate,sioc:has_creator,meta:graphUri,meta:displayName,meta:expandedUri,swa:defaultNamespace,rdfs:label,meta:meta/(meta:hasLinked|semfun:hasMainTag|meta:hasTerm|meta:hasUser)/meta:count
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id" : "model:myExample.tch",
"@type" : [ "sys:Model", "teamwork:Vocabulary" ],
"dcterms:created" : [ {
"@type" : "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
} ],
"semfun:graphLastModificationDate" : [ {
"@type" : "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
} ],
"sioc:has_creator" : [ {
"@id" : "user:Administrator"
} ],
"meta:graphUri" : {"@id":"model:myExample"},
"meta:displayName" : {"@value":"myExample"},
"meta:expandedUri" : {"@value":"urn:x-evn-master:myExample:Administrator"},
"meta:meta" : {
"@id": "_:NNN",
"semfun:hasMainTag" : {
"@id": "_:NNN",
"meta:count" : "!/{\"type\": \"integer\"}/!"
},
"meta:hasUser" : {
"@id": "_:NNN",
"meta:count" : 3
},
"meta:hasLinked" : {
"@id": "_:NNN",
"meta:count" : 0
},
"meta:hasTerm" : {
"@id": "_:NNN",
"meta:count" : 42
}
},
"swa:defaultNamespace" : [ {"@value":"http://proto.smartlogic.com/example#"} ],
"rdfs:label" : [ {"@value":"myExample"} ]
}
]
}Get model with configured languagesGET/sys/{graphUri}{?properties}
Example URI
GET /sys/model:myExample?properties=dcterms:language/skos:notation,dcterms:language/meta:displayName,dcterms:language/dc:title
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: dcterms:language/skos:notation,dcterms:language/meta:displayName,dcterms:language/dc:title
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "model:myExample.tch",
"dcterms:language": [
{
"@id": "lang:en",
"skos:notation": [ {"@value":"en"} ],
"meta:displayName": {
"@language": "en",
"@value": "English"
},
"dc:title": [
{
"@language": "en",
"@value": "English"
}
]
}
]
}
]
}Get all user roles for master modelGET/sys/{graphUri}{?properties,filters}
Example URI
GET /sys/model:myExample?properties=?userRole/meta:displayName&filters=userRole(rdfs:subPropertyOf*=teamwork:role)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: ?userRole/meta:displayName- filters
string(required) Example: userRole(rdfs:subPropertyOf*=teamwork:role)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "model:myExample.tch",
"sempermissions:manager": [
{
"@id": "user:Administrator",
"meta:displayName": {
"@value": "Administrator"
}
},
{
"@id": "role:SemaphoreAdministrators",
"meta:displayName": {
"@value": "SemaphoreAdministrators"
}
}
],
"sempermissions:viewer": [
{
"@id": "role:SemaphoreUsers",
"meta:displayName": {
"@value": "SemaphoreUsers"
}
}
]
}
]
}Add languagePATCH/sys/{graphUri}
Example URI
PATCH /sys/model:${api.model.id}-${api.test.id}
URI Parameters
- graphUri
string(required) Example: model:${api.model.id}-${api.test.id}
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "/@graph/0/dcterms:language/-",
"value": {
"@id": "lang:pl"
}
}
]Response
200Modify multiple language namesPATCH/sys/{graphUri}
Example URI
PATCH /sys/model:${api.model.id}-${api.test.id}
URI Parameters
- graphUri
string(required) Example: model:${api.model.id}-${api.test.id}
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/dcterms:language/0",
"value": {
"@id": "lang:en"
}
},
{
"op": "add",
"path": "@graph/0/dcterms:language/0/dc:title/-",
"value": [
{
"@value": "Angielski",
"@language": "pl"
}
]
},
{
"op": "test",
"path": "@graph/0/dcterms:language/1",
"value": {
"@id": "lang:pl"
}
},
{
"op": "add",
"path": "@graph/0/dcterms:language/1/dc:title/-",
"value": [
{
"@value": "Polish2",
"@language": "en"
},
{
"@value": "Polski",
"@language": "pl"
}
]
}
]Response
200Remove languagePATCH/sys/{graphUri}
Example URI
PATCH /sys/model:${api.model.id}-${api.test.id}
URI Parameters
- graphUri
string(required) Example: model:${api.model.id}-${api.test.id}
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "/@graph/0/dcterms:language/0",
"value": {
"@id": "lang:pl",
"dc:title": {
"@value": "Polish Language",
"@language": "en"
}
}
},
{
"op": "remove",
"path": "/@graph/0/dcterms:language/0"
}
]Response
200Modify user rolesPATCH/sys/{graphUri}
Example URI
PATCH /sys/model:${api.model.id}-${api.test.id}
URI Parameters
- graphUri
string(required) Example: model:${api.model.id}-${api.test.id}
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/sempermissions:editor/0",
"value": {
"@id": "user:ApiTest-19.200655.908-User2"
}
},
{
"op": "remove",
"path": "@graph/0/sempermissions:editor/0"
},
{
"op": "test",
"path": "@graph/0/sempermissions:viewer/0",
"value": {
"@id": "user:ApiTest-19.200655.908-User3"
}
},
{
"op": "remove",
"path": "@graph/0/sempermissions:viewer/0"
},
{
"op": "add",
"path": "@graph/0/sempermissions:manager/-",
"value": {
"@id": "user:ApiTest-19.200655.908-User3"
}
}
]Response
200Delete modelDELETE/sys/{graphUri}
Delete the model and all dependencies that it contained.
As with all deletion requests, a successful deletion should return 204.
Example URI
DELETE /sys/model:myExample-test
URI Parameters
- graphUri
string(required) Example: model:myExample-test
Response
200System Operations - Tasks ¶
Tasks for a model ¶
Retrieve tasks for given modelGET/sys/{graphUri}{?properties,filters}
Example URI
GET /sys/model:myExample?properties=swa:defaultNamespace,semfun:hasMainTag/(dcterms:created|semfun:graphLastModificationDate|meta:displayName|meta:expandedUri|rdfs:label|meta:meta/(meta:hasTerm|meta:hasUser)/meta:count)&filters=subject_hasMainTag(rdfs:label matches "^myExample$")
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: swa:defaultNamespace,semfun:hasMainTag/(dcterms:created|semfun:graphLastModificationDate|meta:displayName|meta:expandedUri|rdfs:label|meta:meta/(meta:hasTerm|meta:hasUser)/meta:count)- filters
string(required) Example: subject_hasMainTag(rdfs:label matches "^myExample$")
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [{
"@id": "model:myExample.tch",
"swa:defaultNamespace" : [{"@value" : "http://proto.smartlogic.com/example#" }],
"semfun:hasMainTag": [ {
"@id": "tag:ApiTest-19.200655.908",
"dcterms:created": [{
"@type": "xsd:dateTime",
"@value": "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}],
"semfun:graphLastModificationDate": [{
"@type": "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}],
"meta:displayName": {"@value":"ApiTest-19.200655.908"},
"meta:expandedUri":{"@value" : "urn:x-evn-tag:myExample:ApiTest-19.200655.908:Administrator"},
"meta:meta": {
"@id": "_:NNN",
"meta:hasTerm": {
"@id": "_:NNN",
"meta:count": 42
},
"meta:hasUser": {
"@id": "_:NNN",
"meta:count": 1
}
},
"rdfs:label": [ {"@value":"ApiTest-19.200655.908"} ]
}]
}]
}Tasks for a model ¶
Create taskPOST/sys/{graphUri}/meta:hasTask
Example URI
POST /sys/model:myExample-test/meta:hasTask
URI Parameters
- graphUri
string(required) Example: model:myExample-test
Request
Headers
Content-Type: application/ld+json
X-Expect-Uri-RelativeTo: ApiEndpointBody
{
"@type": [
"sys:Task"
],
"rdfs:label": "Task C"
}Response
201Headers
Location: ../task:myExample-test:TaskCSingle Task ¶
Get single taskGET/sys/{graphUri}{?properties}
Example URI
GET /sys/task:myExample:ApiTest-19.200655.908?properties=meta:graphUri,dcterms:created,semfun:graphLastModificationDate,meta:taskOf,meta:displayName,meta:expandedUri,swa:defaultNamespace,rdfs:label,meta:meta/meta:hasTerm/meta:count
URI Parameters
- graphUri
string(required) Example: task:myExample:ApiTest-19.200655.908- properties
string(optional) Example: meta:graphUri,dcterms:created,semfun:graphLastModificationDate,meta:taskOf,meta:displayName,meta:expandedUri,swa:defaultNamespace,rdfs:label,meta:meta/meta:hasTerm/meta:count
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [{
"@id": "tag:ApiTest-19.200655.908",
"meta:taskOf": {"@id": "model:myExample.tch"},
"rdfs:label": [{"@value":"ApiTest-19.200655.908"} ],
"meta:displayName":{ "@value": "ApiTest-19.200655.908" },
"dcterms:created": [{
"@type": "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}],
"semfun:graphLastModificationDate": [{
"@type": "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
}],
"meta:graphUri": { "@id": "task:myExample:ApiTest-19.200655.908" },
"meta:expandedUri": {"@value":"urn:x-evn-tag:myExample:ApiTest-19.200655.908:Administrator"},
"meta:meta": {
"@id": "_:NNN",
"meta:hasTerm": {
"@id": "_:NNN",
"meta:count": 42
}
}
}]
}Get all user roles for taskGET/sys/{graphUri}{?properties,filters}
Example URI
GET /sys/task:myExample:ApiTest-19.200655.908?properties=?userRole/meta:displayName&filters=userRole(rdfs:subPropertyOf*=teamwork:role)
URI Parameters
- graphUri
string(required) Example: task:myExample:ApiTest-19.200655.908- properties
string(required) Example: ?userRole/meta:displayName- filters
string(required) Example: userRole(rdfs:subPropertyOf*=teamwork:role)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph": [
{
"@id": "tag:ApiTest-19.200655.908",
"sempermissions:manager": [
{
"@id": "user:Administrator",
"meta:displayName": {
"@value": "Administrator"
}
}
]
}
]
}Modify rolesPATCH/sys/{graphUri}
Example URI
PATCH /sys/task:${api.model.id}:${api.task.id}
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.task.id}
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/sempermissions:editor/0",
"value": {
"@id": "user:ApiTest-19.200655.908-User2"
}
},
{
"op": "remove",
"path": "@graph/0/sempermissions:editor/0"
},
{
"op": "test",
"path": "@graph/0/sempermissions:viewer/0",
"value": {
"@id": "user:ApiTest-19.200655.908-User3"
}
},
{
"op": "remove",
"path": "@graph/0/sempermissions:viewer/0"
},
{
"op": "add",
"path": "@graph/0/sempermissions:manager/-",
"value": {
"@id": "user:ApiTest-19.200655.908-User3"
}
}
]Response
200Delete taskDELETE/sys/{graphUri}
Delete the task and all triples that it contained. As with all deletion requests, a successful deletion should return 204.
Example URI
DELETE /sys/task:${api.model.id}:${api.task.id}
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.task.id}
Response
200Commit the task to masterPOST/sys/{graphUri}{?action}
Example URI
POST /sys/task:myExample-test:task1?action=commit
URI Parameters
- graphUri
string(required) Example: task:myExample-test:task1- action
string(required) Example: commit
Request
Headers
X-ApiTestHook-SaveFromHeaders: __LOCATION__:(headers) => headers["location"]
X-ApiTestHook-VerifyPlaceholderValue: __LOCATION__:^./model:myExample-test/%3Curn:x-commit:task1-[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}-[0-9]{2}-[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})%3E$Response
201System Operations - Import ¶
This example shows how to import a model.
Create new model ¶
Create new modelPOST/sys/sys:Model/rdf:instance
Example URI
POST /sys/sys:Model/rdf:instance
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"sys:Model"
],
"rdfs:label": "myModel"
}Response
201Import an example model into newly created one ¶
Import an example model into newly created onePOST/backup/model:myModel/import
Example URI
POST /backup/model:myModel/import
Request
Headers
Content-Type: multipart/form-data;boundary=----WebKitFormBoundary8M3sSU13ul5lXSJmBody
------WebKitFormBoundary8M3sSU13ul5lXSJm
Content-Disposition: form-data; name="format"
rdf/xml
------WebKitFormBoundary8M3sSU13ul5lXSJm
Content-Disposition: form-data; name="file"
<?xml version="1.0"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:skosxl="http://www.w3.org/2008/05/skos-xl#"
xmlns:spin="http://spinrdf.org/spin#">
<owl:Ontology rdf:about="urn:x-evn-master:test">
<rdf:type rdf:resource="http://topbraid.org/teamwork#Vocabulary"/>
<spin:imports rdf:resource="http://www.smartlogic.com/2015/12/unique-concept-label-constraint"/>
<spin:imports rdf:resource="http://www.smartlogic.com/2015/12/unique-concept-label-in-class-constraint"/>
<spin:imports rdf:resource="http://www.smartlogic.com/2015/02/semaphore-spin-constraints"/>
<owl:imports rdf:resource="http://www.smartlogic.com/2014/08/semaphore-core"/>
</owl:Ontology>
<skos:ConceptScheme rdf:about="http://proto.smartlogic.com/example#:Cities">
<rdfs:label xml:lang="en">Countries</rdfs:label>
<skos:hasTopConcept>
<skos:Concept rdf:about="http://proto.smartlogic.com/example#:Warsaw">
<skosxl:prefLabel>
<skosxl:Label rdf:about="http://proto.smartlogic.com/example#:Warsaw_en">
<skosxl:literalForm xml:lang="en">Warsaw</skosxl:literalForm>
</skosxl:Label>
</skosxl:prefLabel>
</skos:Concept>
</skos:hasTopConcept>
</skos:ConceptScheme>
</rdf:RDF>
------WebKitFormBoundary8M3sSU13ul5lXSJm--Response
200Headers
Content-Type: application/jsonBody
{
"message": "File with 8 statements has been imported successfully.",
"notes": []
}System Operations - Export ¶
The following example demonstrates the model export.
Export of an example model ¶
Export of an example modelGET/backup/model:myExample/export{?serialization}
Example URI
GET /backup/model:myExample/export?serialization=NTriple
URI Parameters
- serialization
string(optional) Example: NTriple
Response
200Headers
Content-Disposition: attachment; filename="myExample.nt"Model Structure - Overview ¶
Basic CRUD operations on Classes, skosxl:altLabels, metadata property definition and relationship definitions.
Model Structure - Classes ¶
All Classes ¶
Get subclasses of example:SectorGET/{graphUri}/{conceptClass}/meta:transitiveSubClass{?properties,limit}
Example URI
GET /model:myExample/example:Sector/meta:transitiveSubClass?properties=meta:displayName&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: meta:displayName- limit
string(required) Example: 100- conceptClass
string(required) Example: example:Sector
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:Sector",
"meta:displayName" : {
"@language" : "en",
"@value" : "Sector"
}
} ]
}Create new ConceptClass in a taskPOST/{graphUri}/{conceptClass}/meta:transitiveSubClass{?properties,limit}
Example URI
POST /model:myExample/conceptClass/meta:transitiveSubClass?properties=meta:displayName&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName- limit
string(required) Example: 100
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Class1",
"@type": [
"owl:Class"
],
"rdfs:label": {
"@value": "Concept class name",
"@language": "en"
},
"rdfs:subClassOf": {
"@id": "skos:Concept"
}
}Response
201Headers
Location: ../example:Class1Single Class ¶
Get details of example:SectorGET/{graphUri}/{conceptClass}{?properties}
Example URI
GET /model:myExample/example:Sector?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName- conceptClass
string(required) Example: example:Sector
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [{
"@id" : "example:Sector",
"meta:displayName" : {
"@language" : "en",
"@value" : "Sector"
},
"rdfs:subClassOf" : [ {
"@id" : "skos:Concept",
"meta:displayName" : {
"@language" : "en",
"@value" : "Concept"
}
}]
}
]
}Get concept labelsGET/{graphUri}/{conceptClass}{?properties}
Example URI
GET /model:myExample/conceptClass?properties=rdfs:label
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: rdfs:label
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:Topic",
"rdfs:label" : [ {
"@language" : "en",
"@value" : "Topic"
} ]
} ]
}Get list of example:Company subclassesGET/{graphUri}/{conceptClass}{?properties}
Example URI
GET /model:myExample/example:Company?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName- conceptClass
string(required) Example: example:Company
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [
{
"@id": "example:Company",
"meta:displayName" : {
"@value" : "Company",
"@language" : "en"
},
"rdfs:hasSubClass" : [
{
"@id" : "example:CicCompany",
"meta:displayName" : {
"@language" : "en",
"@value" : "CIC Company"
},
"meta:meta" : {
"@id": "_:NNN",
"rdfs:hasSubClass" : {
"@id": "_:NNN",
"meta:exist" : false
}
}
},
{
"@id" : "example:CioCompany",
"meta:displayName" : {
"@language" : "en",
"@value" : "CIO Company"
},
"meta:meta" : {
"@id": "_:NNN",
"rdfs:hasSubClass" : {
"@id": "_:NNN",
"meta:exist" : false
}
}
}, {
"@id" : "example:PrivateCompany",
"meta:displayName" : {
"@value" : "Private Company",
"@language" : "en"
},
"meta:meta" : {
"@id": "_:NNN",
"rdfs:hasSubClass" : {
"@id": "_:NNN",
"meta:exist" : true
}
}
}
]
}
]
}Add labelPATCH/{graphUri}/{conceptClass}{?properties}
Example URI
PATCH /model:myExample/conceptClass?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/rdfs:label/-",
"value": {
"@value": "Nazwa klasy",
"@language": "pl"
}
}
]Response
200Remove labelPATCH/{graphUri}/{conceptClass}{?properties}
Example URI
PATCH /model:myExample/conceptClass?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Concept class name",
"@language": "en"
}
},
{
"op": "remove",
"path": "@graph/0/rdfs:label/0"
}
]Response
200Replace labelPATCH/{graphUri}/{conceptClass}{?properties}
Example URI
PATCH /model:myExample/conceptClass?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Concept class name",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "New Concept Class Name",
"@language": "en"
}
}
]Response
200Add commentPATCH/{graphUri}/{conceptClass}{?properties}
Example URI
PATCH /model:myExample/conceptClass?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/rdfs:comment/-",
"value": "New Concept Class comment"
}
]Response
200Replace commentPATCH/{graphUri}/{conceptClass}{?properties}
Example URI
PATCH /model:myExample/conceptClass?properties=meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
URI Parameters
- graphUri
string(required) Example: model:myExample- conceptClass
string(required)- properties
string(required) Example: meta:displayName,rdfs:hasSubClass/meta:displayName,rdfs:subClassOf/meta:displayName
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:comment/0",
"value": "Concept class comment"
},
{
"op": "replace",
"path": "@graph/0/rdfs:comment/0",
"value": "New Concept Class Comment"
}
]Response
200Delete an empty classDELETE/{graphUri}/{concepClasstUri}{?mode}
Example URI
DELETE /task:myExample:test/example:ClassToRemove?mode=empty
URI Parameters
- graphUri
string(required) Example: task:myExample:test- concepClasstUri
string(required) Example: example:ClassToRemove- mode
string(required) Example: empty
Response
200Delete class and re-attach its instancesDELETE/{graphUri}/{concepClasstUri}{?mode}
Example URI
DELETE /task:myExample:test/example:ClassToRemove?mode=reattachInstances
URI Parameters
- graphUri
string(required) Example: task:myExample:test- concepClasstUri
string(required) Example: example:ClassToRemove- mode
string(required) Example: reattachInstances
Response
201Headers
X-Location-Uri: example:BlockingConceptModel Structure - altLabels ¶
All skosxl:altLabels ¶
Get sub-properties of skosxl:altLabel with domain matching type of given conceptGET/{graphUri}/skosxl:altLabel/meta:transitiveSubProperty{?properties,filters}
Example URI
GET /model:myExample/skosxl:altLabel/meta:transitiveSubProperty?properties=&filters=subject(rdfs:domain/semfun:transitiveInstance=example:Semaphore)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional)- filters
string(required) Example: subject(rdfs:domain/semfun:transitiveInstance=example:Semaphore)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [
{
"@id": "sem:forcedPreclusion",
"meta:displayName": {
"@value": "forced preclusion"
}
},
{
"@id" : "example:acronym",
"meta:displayName" : {
"@language" : "en",
"@value" : "acronym"
}
},
{
"@id" : "skosxl:altLabel",
"meta:displayName" : {
"@language" : "en",
"@value" : "alternative label"
}
},
{
"@id" : "example:code",
"meta:displayName" : {
"@language" : "en",
"@value" : "code"
}
},
{
"@id" : "example:sign",
"meta:displayName" : {
"@value" : "sign",
"@language" : "en"
}
}
]
}Create new alt label property in a taskPOST/{graphUri}/skosxl:altLabel/meta:transitiveSubProperty{?properties,filters}
Example URI
POST /model:myExample/skosxl:altLabel/meta:transitiveSubProperty?properties=&filters=
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional)- filters
string(optional)
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:testAcronym",
"@type": [
"owl:ObjectProperty"
],
"rdfs:label": [
{
"@language": "en",
"@value": "test acronym"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "skosxl:Label"
}
],
"rdfs:subPropertyOf": [
{
"@id": "skosxl:altLabel"
}
],
"rdfs:comment": [
{
"@language": "en",
"@value": "Comment to the example:testAcronym."
}
]
}Response
201Headers
X-Location-Uri: example:testAcronymSingle skosxl:altLabel ¶
Get details of example:codeGET/{graphUri}/{propertyUri}{?properties}
Example URI
GET /model:myExample/example:code?properties=meta:displayName,rdfs:domain,rdfs:range,rdfs:comment,rdfs:subPropertyOf
URI Parameters
- graphUri
string(required) Example: model:myExample- propertyUri
string(required) Example: example:code- properties
string(optional) Example: meta:displayName,rdfs:domain,rdfs:range,rdfs:comment,rdfs:subPropertyOf
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:code",
"meta:displayName" : {
"@language" : "en",
"@value" : "code"
},
"rdfs:domain" : [ {
"@id" : "skos:Concept"
} ],
"rdfs:range" : [ {
"@id" : "skosxl:Label"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skosxl:altLabel"
} ]
} ]
}Delete propertyDELETE/{graphUri}/{propertyUri}
Example URI
DELETE /task:myExample:test/example:propertyToRemove
URI Parameters
- graphUri
string(required) Example: task:myExample:test- propertyUri
string(required) Example: example:propertyToRemove
Response
200Model Structure - Metadata ¶
All properties ¶
Get metadata properties allowed for all Concepts by sem:DefaultPropertyGET/{graphUri}{?filters,properties}
Example URI
GET /model:myExample?filters=subject(semfun:effectiveRange=?range),range(rdf:type=rdfs:Datatype),subject(a=sem:DefaultProperty)&properties=
URI Parameters
- graphUri
string(required) Example: model:myExample- filters
string(required) Example: subject(semfun:effectiveRange=?range),range(rdf:type=rdfs:Datatype),subject(a=sem:DefaultProperty)- properties
string(optional)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id": "rdfs:comment"
}, {
"@id": "skos:definition"
}, {
"@id" : "skos:editorialNote"
}, {
"@id" : "skos:historyNote"
}, {
"@id" : "skos:note"
}, {
"@id" : "skos:scopeNote"
} ]
}Get metadata properties allowed for Concepts by rdfs:domainGET/{graphUri}{?filters,properties}
Example URI
GET /model:myExample?filters=subject(rdfs:range/a=rdfs:Datatype),subject(rdfs:domain=?class),class(rdfs:subClassOf*=skos:Concept)&properties=
URI Parameters
- graphUri
string(required) Example: model:myExample- filters
string(required) Example: subject(rdfs:range/a=rdfs:Datatype),subject(rdfs:domain=?class),class(rdfs:subClassOf*=skos:Concept)- properties
string(optional)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:established"
}, {
"@id" : "example:is401established"
}, {
"@id" : "example:issuedShareCapital"
} ]
}Create new boolean metadata propertyPOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:booleanProperty",
"@type": [
"owl:DatatypeProperty"
],
"rdfs:label": [
{
"@value": "boolean property",
"@language": "en"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "xsd:boolean"
}
]
}Response
201Headers
x-location-uri: example:booleanPropertyCreate new integer metadata propertyPOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:integerProperty",
"@type": [
"owl:DatatypeProperty"
],
"rdfs:label": [
{
"@value": "integer property",
"@language": "en"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "xsd:integer"
}
]
}Response
201Single property ¶
Replace labelPATCH/{graphUri}/{propertyUri}{?properties}
Example URI
PATCH /model:myExample/example:code?properties=meta:displayName,rdfs:domain,rdfs:range,rdfs:comment,rdfs:subPropertyOf
URI Parameters
- graphUri
string(required) Example: model:myExample- propertyUri
string(required) Example: example:code- properties
string(optional) Example: meta:displayName,rdfs:domain,rdfs:range,rdfs:comment,rdfs:subPropertyOf
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "integer property",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "new integer property",
"@language": "en"
}
}
]Response
200Delete propertyDELETE/{graphUri}/{propertyUri}
Example URI
DELETE /task:myExample:test/example:propertyToRemove
URI Parameters
- graphUri
string(required) Example: task:myExample:test- propertyUri
string(required) Example: example:propertyToRemove
Response
200Model Structure - Hierarchical Relations ¶
All Properties ¶
Get hierarchical properties for from skos:broaderGET/{graphUri}/skos:broader/meta:transitiveSubProperty{?properties}
Example URI
GET /model:myExample/skos:broader/meta:transitiveSubProperty?properties=rdfs:label,owl:inverseOf,rdfs:subPropertyOf,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:subPropertyOf
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: rdfs:label,owl:inverseOf,rdfs:subPropertyOf,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:subPropertyOf
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "skos:broader",
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has broader"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:broaderTransitive"
} ],
"owl:inverseOf" : [ {
"@id" : "skos:narrower",
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has narrower"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:narrowerTransitive"
} ]
} ]
}, {
"@id" : "skos:broadMatch",
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has broader match"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:broader"
}, {
"@id" : "skos:mappingRelation"
},
{
"@id": "semmaprel:MappingRelationship"
} ],
"owl:inverseOf" : [ {
"@id" : "skos:narrowMatch",
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has narrower match"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:narrower"
}, {
"@id" : "skos:mappingRelation"
},
{
"@id": "semmaprel:MappingRelationship"
} ]
} ]
} ]
}Create new hierarchical propertyPOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:bigger",
"@type": [
"owl:ObjectProperty"
],
"rdfs:label": [
{
"@language": "en",
"@value": "bigger than property"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "skos:Concept"
}
],
"rdfs:subPropertyOf": [
{
"@id": "skos:broader"
}
],
"rdfs:comment": [
{
"@language": "en",
"@value": "comment to the example:bigger."
}
],
"owl:inverseOf": [
{
"@id": "example:smaller",
"@type": [
"owl:ObjectProperty"
],
"rdfs:label": [
{
"@language": "en",
"@value": "smaller than property"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "skos:Concept"
}
],
"rdfs:subPropertyOf": [
{
"@id": "skos:narrower"
}
],
"rdfs:comment": [
{
"@language": "en",
"@value": "comment to the example:smaller."
}
],
"owl:inverseOf": [
{
"@id": "example:bigger"
}
]
}
]
}Response
201Single Property ¶
Get subproperties of skos:related inclusiveGET/{graphUri}/{propertyUri}{?properties}
Example URI
GET /model:myExample/skos:broader?properties=rdfs:label,rdfs:domain,rdfs:range,owl:inverseOf,rdfs:comment,rdfs:subPropertyOf,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:domain,owl:inverseOf/rdfs:range,owl:inverseOf/rdfs:comment,owl:inverseOf/rdfs:subPropertyOf
URI Parameters
- graphUri
string(required) Example: model:myExample- propertyUri
string(required) Example: skos:broader- properties
string(optional) Example: rdfs:label,rdfs:domain,rdfs:range,owl:inverseOf,rdfs:comment,rdfs:subPropertyOf,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:domain,owl:inverseOf/rdfs:range,owl:inverseOf/rdfs:comment,owl:inverseOf/rdfs:subPropertyOf
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "skos:broader",
"rdfs:comment" : [ {
"@language" : "en",
"@value" : "Broader concepts are typically rendered as parents in a concept hierarchy (tree)."
} ],
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has broader"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:broaderTransitive"
} ],
"owl:inverseOf" : [ {
"@id" : "skos:narrower",
"rdfs:comment" : [ {
"@language" : "en",
"@value" : "Narrower concepts are typically rendered as children in a concept hierarchy (tree)."
} ],
"rdfs:label" : [ {
"@language" : "en",
"@value" : "has narrower"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:narrowerTransitive"
} ]
} ]
} ]
}Delete relation propertyDELETE/{graphUri}/{propertyUri}{?mode}&dryRun=false
Example URI
DELETE /task:myExample:test/example:propertyForward?mode=empty&dryRun=false
URI Parameters
- graphUri
string(required) Example: task:myExample:test- propertyUri
string(required) Example: example:propertyForward- mode
string(required) Example: empty
Response
200Model Structure - Associative Relations ¶
All Properties ¶
Get subproperties of skos:related inclusiveGET/{graphUri}/skos:related/meta:transitiveSubProperty{?properties}
Example URI
GET /model:myExample/skos:related/meta:transitiveSubProperty?properties=meta:displayName,owl:inverseOf,rdfs:subPropertyOf,rdfs:range,rdfs:domain
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: meta:displayName,owl:inverseOf,rdfs:subPropertyOf,rdfs:range,rdfs:domain
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:companiesInSector",
"meta:displayName" : {
"@language" : "en",
"@value" : "companies in sector"
},
"rdfs:domain" : [ {
"@id" : "example:Sector"
} ],
"rdfs:range" : [ {
"@id" : "example:Company"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:sector"
} ]
}, {
"@id" : "example:companiesInSubSector",
"meta:displayName" : {
"@language" : "en",
"@value" : "companies in sub sector"
},
"rdfs:subPropertyOf" : [ {
"@id" : "example:companiesInSector"
} ],
"owl:inverseOf" : [ {
"@id" : "example:subSector"
} ]
}, {
"@id" : "example:equivalentCompany",
"meta:displayName" : {
"@language" : "en",
"@value" : "equivalent company"
},
"rdfs:domain" : [ {
"@id" : "example:Company"
} ],
"rdfs:range" : [ {
"@id" : "example:Company"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ]
}, {
"@id" : "skos:related",
"meta:displayName" : {
"@language" : "en",
"@value" : "has related"
},
"rdfs:domain" : [ {
"@id" : "skos:Concept"
} ],
"rdfs:range" : [ {
"@id" : "skos:Concept"
} ],
"rdfs:subPropertyOf" : [ {
"@id": "sem:relatedConcept"
}, {
"@id" : "skos:semanticRelation"
} ]
}, {
"@id" : "skos:relatedMatch",
"meta:displayName" : {
"@language" : "en",
"@value" : "has related match"
},
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
}, {
"@id": "skos:mappingRelation"
}, {
"@id": "semmaprel:MappingRelationship"
} ]
}, {
"@id" : "example:management",
"meta:displayName" : {
"@language" : "en",
"@value" : "management"
},
"rdfs:domain" : [ {
"@id" : "example:Company"
} ],
"rdfs:range" : [ {
"@id" : "example:Executive"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:managementOf"
} ]
}, {
"@id" : "example:managementOf",
"meta:displayName" : {
"@language" : "en",
"@value" : "management of"
},
"rdfs:domain" : [ {
"@id" : "example:Executive"
} ],
"rdfs:range" : [ {
"@id" : "example:Company"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:management"
} ]
}, {
"@id" : "example:producedBy",
"meta:displayName" : {
"@language" : "en",
"@value" : "produced by"
},
"rdfs:domain" : [ {
"@id" : "example:Brand"
} ],
"rdfs:range" : [ {
"@id" : "example:Company"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:produces"
} ]
}, {
"@id" : "example:produces",
"meta:displayName" : {
"@language" : "en",
"@value" : "produces"
},
"rdfs:domain" : [ {
"@id" : "example:Company"
} ],
"rdfs:range" : [ {
"@id" : "example:Brand"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:producedBy"
} ]
}, {
"@id" : "example:sector",
"meta:displayName" : {
"@language" : "en",
"@value" : "sector"
},
"rdfs:domain" : [ {
"@id" : "example:Company"
} ],
"rdfs:range" : [ {
"@id" : "example:Sector"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ],
"owl:inverseOf" : [ {
"@id" : "example:companiesInSector"
} ]
}, {
"@id" : "example:subSector",
"meta:displayName" : {
"@language" : "en",
"@value" : "sub sector"
},
"rdfs:subPropertyOf" : [ {
"@id" : "example:sector"
} ],
"owl:inverseOf" : [ {
"@id" : "example:companiesInSubSector"
} ]
} ]
}Create new associative propertyPOST/{graphUri}/skos:related/meta:transitiveSubProperty{?properties}
Example URI
POST /model:myExample/skos:related/meta:transitiveSubProperty?properties=meta:displayName,owl:inverseOf,rdfs:subPropertyOf,rdfs:range,rdfs:domain
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional) Example: meta:displayName,owl:inverseOf,rdfs:subPropertyOf,rdfs:range,rdfs:domain
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:associativeProperty",
"@type": [
"owl:ObjectProperty"
],
"rdfs:label": [
{
"@language": "en",
"@value": "test associative property"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "skos:Concept"
}
],
"rdfs:subPropertyOf": [
{
"@id": "skos:related"
}
],
"rdfs:comment": [
{
"@language": "en",
"@value": "comment to the example:associativeProperty."
}
],
"owl:inverseOf": [
{
"@id": "example:associativePropertyOf",
"@type": [
"owl:ObjectProperty"
],
"rdfs:label": [
{
"@language": "en",
"@value": "reverse test associative property"
}
],
"rdfs:domain": [
{
"@id": "skos:Concept"
}
],
"rdfs:range": [
{
"@id": "skos:Concept"
}
],
"rdfs:subPropertyOf": [
{
"@id": "skos:related"
}
],
"rdfs:comment": [
{
"@language": "en",
"@value": "comment to the example:associativePropertyOf."
}
],
"owl:inverseOf": [
{
"@id": "example:associativeProperty"
}
]
}
]
}Response
201Single Property ¶
Get subproperties of skos:related inclusiveGET/{graphUri}/{propertyUri}{?properties}
Example URI
GET /model:myExample/example:sector?properties=meta:displayName,(rdfs:domain|rdfs:range|owl:inverseOf|rdfs:subPropertyOf)/meta:displayName,rdfs:comment,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:domain,owl:inverseOf/rdfs:range,owl:inverseOf/rdfs:comment,owl:inverseOf/rdfs:subPropertyOf
URI Parameters
- graphUri
string(required) Example: model:myExample- propertyUri
string(required) Example: example:sector- properties
string(optional) Example: meta:displayName,(rdfs:domain|rdfs:range|owl:inverseOf|rdfs:subPropertyOf)/meta:displayName,rdfs:comment,owl:inverseOf/rdfs:label,owl:inverseOf/rdfs:domain,owl:inverseOf/rdfs:range,owl:inverseOf/rdfs:comment,owl:inverseOf/rdfs:subPropertyOf
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:sector",
"meta:displayName" : {
"@language" : "en",
"@value" : "sector"
},
"rdfs:domain" : [ {
"@id" : "example:Company",
"meta:displayName" : {
"@language" : "en",
"@value" : "Company"
}
} ],
"rdfs:range" : [ {
"@id" : "example:Sector",
"meta:displayName" : {
"@language" : "en",
"@value" : "Sector"
}
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related",
"meta:displayName" : {
"@language" : "en",
"@value" : "has related"
}
} ],
"owl:inverseOf" : [ {
"@id" : "example:companiesInSector",
"meta:displayName" : {
"@language" : "en",
"@value" : "companies in sector"
},
"rdfs:domain" : [ {
"@id" : "example:Sector"
} ],
"rdfs:label" : [ {
"@language" : "en",
"@value" : "companies in sector"
} ],
"rdfs:range" : [ {
"@id" : "example:Company"
} ],
"rdfs:subPropertyOf" : [ {
"@id" : "skos:related"
} ]
} ]
} ]
}Delete relation propertyDELETE/{graphUri}/{propertyUri}{?mode}&dryRun=false
Example URI
DELETE /task:myExample:test/example:propertyForward?mode=empty&dryRun=false
URI Parameters
- graphUri
string(required) Example: task:myExample:test- propertyUri
string(required) Example: example:propertyForward- mode
string(required) Example: empty
Response
200Changes ¶
Get all changes with basic summary info ¶
Get all changes with basic summary infoGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=sem:about/meta:displayName,dcterms:created,sioc:has_creator,rdfs:comment,sem:committed&sort=dcterms:created
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: sem:about/meta:displayName,dcterms:created,sioc:has_creator,rdfs:comment,sem:committed- sort
string(required) Example: dcterms:created
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"dcterms:created" : [ {
"@type" : "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
} ],
"sioc:has_creator" : [ {
"@id" : "user:Administrator"
} ],
"sem:about" : [ {
"@id" : "example:cs1",
"meta:displayName" : {
"@language" : "en",
"@value" : "new label"
}
} ]
}, {
"@id" : "%/^urn:x-change:/%",
"dcterms:created" : [ {
"@type" : "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
} ],
"sioc:has_creator" : [ {
"@id" : "user:Administrator"
} ],
"sem:about" : [ {
"@id" : "example:cs1"
} ]
} ],
"@context": {...}
}Get changes of given resource with summary info ¶
Get changes of given resource with summary infoGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,filters,sort}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=sem:about/meta:displayName,dcterms:created,sioc:has_creator,rdfs:comment&filters=subject(sem:about=example:cs1)&sort=dcterms:created
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: sem:about/meta:displayName,dcterms:created,sioc:has_creator,rdfs:comment- filters
string(required) Example: subject(sem:about=example:cs1)- sort
string(required) Example: dcterms:created
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"dcterms:created" : [ {
"@type" : "xsd:dateTime",
"@value" : "%/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]+)?(Z|[+-][0-9]{2}(:)?[0-9]{2})$/%"
} ],
"sioc:has_creator" : [ {
"@id" : "user:Administrator"
} ],
"sem:about" : [ {
"@id" : "example:cs1",
"meta:displayName" : {
"@value" : "first"
}
} ]
} ],
"@context": {...}
}Get changes with triple-level details ¶
Get changes with triple-level detailsGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=teamwork:added/?bNodeAdded/meta:displayName,teamwork:deleted/?bNodeDeleted/meta:displayName
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: teamwork:added/?bNodeAdded/meta:displayName,teamwork:deleted/?bNodeDeleted/meta:displayName
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"teamwork:added" : [ {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@value" : "AAAA0000-AA00-AA00-AA00-AAAAAA000000"
} ],
"teamwork:predicate" : [ {
"@id" : "sem:guid",
"meta:displayName" : {
"@value" : "GUID"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Drinks",
"meta:displayName" : {
"@language" : "en",
"@value" : "Drinks_EN"
}
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@id" : "skos:Concept",
"meta:displayName" : {
"@language" : "en",
"@value" : "Concept"
}
} ],
"teamwork:predicate" : [ {
"@id" : "rdf:type",
"meta:displayName" : {
"@value" : "type"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Drinks"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@id" : "example:Drinks/Drinks_EN_en",
"meta:displayName" : {
"@language" : "en",
"@value" : "Drinks_EN"
}
} ],
"teamwork:predicate" : [ {
"@id" : "skosxl:prefLabel",
"meta:displayName" : {
"@language" : "en",
"@value" : "preferred label"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Drinks"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@id" : "skosxl:Label",
"meta:displayName" : {
"@language" : "en",
"@value" : "Label"
}
} ],
"teamwork:predicate" : [ {
"@id" : "rdf:type"
} ],
"teamwork:subject" : [ {
"@id" : "example:Drinks/Drinks_EN_en"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@language" : "en",
"@value" : "Drinks_EN"
} ],
"teamwork:predicate" : [ {
"@id" : "skosxl:literalForm",
"meta:displayName" : {
"@language" : "en",
"@value" : "literal form"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Drinks/Drinks_EN_en"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@value" : "AAAA0000-AA00-AA00-AA00-AAAAAA000000"
} ],
"teamwork:predicate" : [ {
"@id" : "sem:guid"
} ],
"teamwork:subject" : [ {
"@id" : "example:Topics",
"meta:displayName" : {
"@language" : "en",
"@value" : "Topics"
}
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@id" : "skos:ConceptScheme",
"meta:displayName" : {
"@language" : "en",
"@value" : "Concept Scheme"
}
} ],
"teamwork:predicate" : [ {
"@id" : "rdf:type"
} ],
"teamwork:subject" : [ {
"@id" : "example:Topics"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@language" : "en",
"@value" : "Topics"
} ],
"teamwork:predicate" : [ {
"@id" : "rdfs:label",
"meta:displayName" : {
"@value" : "label"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Topics"
} ]
}, {
"@id" : "_:NNN",
"teamwork:object" : [ {
"@id" : "example:Drinks"
} ],
"teamwork:predicate" : [ {
"@id" : "skos:hasTopConcept",
"meta:displayName" : {
"@language" : "en",
"@value" : "has top concept"
}
} ],
"teamwork:subject" : [ {
"@id" : "example:Topics"
} ]
} ]
} ],
"@context": {...}
}Change Notifications ¶
You can register notification listeners for each model. Notifications are http GET request performed to the URL specified in the notification subscription. Notification listener will be notified about the fact that a change has been performed to the model, but the notification itself will not contain the details of that change.
How to subscribe to notifications
If you want to receive notifications about changes made to the model execute the following sparql update in OE Sparql Editor
PREFIX semlisteners: <http://www.smartlogic.com/2016/10/semaphore-listeners#>
WITH <urn:x-evn-master:MODEL_ID.tch>
INSERT {
<urn:x-evn-master:MODEL_ID.tch> semlisteners:hasListener <http://example.com#LISTENER_ID> .
<http://example.com#LISTENER_ID> a semlisteners:Listener.
<http://example.com#LISTENER_ID> semlisteners:listenerUrl "http://localhost:5082" .
} WHERE {}Replace the MODEL_ID and LISTENER_ID with proper values and replace "http://localhost:5082" with the URL that should be requested to notify listener about new changes.
You can also use the REST API
PATCH http://workbench.example.com/api/sys/model:myExample/
[
{
"op": "add",
"path": "@graph/0/semlisteners:hasListener/-",
"value":{
"@id": "http://example.com#LISTENER_ID",
"@type": "semlisteners:Listener",
"semlisteners:listenerUrl": ["http://localhost:5082"]
}
}
]If you want to remove the subscription send the following request
PATCH http://workbench.example.com/api/sys/model:myExample/
[
{
"op": "test",
"path": "@graph/0/semlisteners:hasListener/-",
"value":{
"@id": "http://example.com#LISTENER_ID",
"@type": "semlisteners:Listener",
"semlisteners:listenerUrl": ["http://localhost:5082"]
}
}, {
"op": "remove",
"path": "@graph/0/semlisteners:hasListener/-"
}
]If your notification listener API requires that the caller (OE server) send additional request headers, you will need to create the header item with its name and value in the tch graph for the model and attach it to the listener that you have just created. For example, the following creates such a header and attaches it to the listener with the URI http://example.com/LISTENER_ID. This header has name “X-MyHeader” and value “AValuePossibleAToken”.
This should be run in the SPARQL editor within OE.
PREFIX semlisteners: http://www.smartlogic.com/2016/10/semaphore-listeners#
WITH urn:x-evn-master:MODEL_ID.tch
INSERT {
http://example.com#LISTENER_ID semlisteners:headers http://example.com#LISTENER_ID_Header1 .
http://example.com#LISTENER_ID_Header1 a semlisteners:ListenerHeader .
http://example.com#LISTENER_ID_Header1 semlisteners:headerName "X-MyHeader" .
http://example.com#LISTENER_ID_Header1 semlisteners:headerValue "AValuePossiblyAToken" .
} WHERE {}
You can also use the REST API
PATCH http://workbench.example.com/api/sys/model:MODEL_ID/<http%3A%2F%2Fexample.com#LISTENER_ID>
[
{
"op": "add",
"path": "@graph/0/semlisteners:headers/-",
"value":{
"@id": "http://example.com#LISTENER_ID_Header1",
"@type": "semlisteners:ListenerHeader",
"semlisteners:headerName": ["X-MyHeader"],
"semlisteners:headerValue": ["AValuePossiblyAToken"]
}
}
]When notifications are sent
Notifications are sent in 4 situations:
-
a change has been made to the master model which has a listener assigned
-
a change has been committed from task to a master of a model which has a listener assigned
-
a change has been made to the master model which is linked to a model that has a listener assigned (this also means models linked by other models)
-
a change has been committed from task to a master of a model which is linked to a model that has a listener assigned.
How notifications are sent
Notification are sent as http GET requests to the specified URL with the following query parameters added:
-
modifiedGraphId- ID of the model which was changed -
affectedGraphId- ID of a model which generated the notification (the one that has the listener) -
lastChangeDate- timestamp of the change which generated this notification. The timestamp is formatted according to ISO 8601
modifiedGraphId and affectedGraphId will be the same if the modification was made directly
to the model which has a subscription, but will have different values if a linked model is modified. Example notification url:
How to receive change details
Client application which wants to fetch the details of performed changes should store the timestamp of a last inspected change and perform the following GET request to the OE’s REST API
/api/tchmodel:MODEL_ID/teamwork:Change/rdf:instance?properties=?triple/(teamwork:subject|teamwork:predicate|teamwork:object),sem:committed&filters=subject(sem:committed >= “2016-01-01T08:00:00.000Z”^^xsd:dateTime)&sort=sem:committed&noInnerSort=true
This will return a list of changes since the date specified in the request. Each change will contain a list of deleted and added triples.
Note, that the addition of the noInnerSort=true parameter is important to achieve optimal
performance of the operation.
Please note that the uri of a model is specified as tchModel:MODEL_ID. This will return changes made directly to the model and also
to all linked submodels. If you want to get only changes made directly to the model then use /api/sys/model:MODEL_ID instead of /api/tchmodel:MODEL_ID
If you want to enable paging of the results you can also add limit and offset parameters to the query. E.g ...&limit=10&offset=10 will return the results 11 to 20.
The above API call can be also simplified with its equivalent
/api/tchmodel:MODEL_ID/changes?since=2016-01-01T08:00:00.000Z
Using the simplified API call you can also fetch additional properties or use paging parameters e.g.
/api/tchmodel:MODEL_ID/changes?since=2016-01-01T08:00:00.000Z&properties=sioc:has_creator,dcterms:created&limit=10&offset=10
Transaction Messages ¶
When issuing POST/PATCH/DELETE requests that result in modifying the data in model/task, you can optionally provide a transaction messages. This message will be persisted in history and visible when changes are later retrieved. Two format of messages are supported:
Simple text message
This type of message is provided using X-Transaction-Message HTTP header.
In this case this is just an arbitrary text string.
No support for translation or message paramters are provided in this case.
Structured JSON message
This type of message is provided using X-Transaction-Message-Json HTTP header.
The value of the header should be a valid JSON with two keys:
-
templateKey: this is a key used to lookup a message template -
params: set of parameters that given template requires
Create ConceptScheme with text transaction message ¶
Create ConceptScheme with text transaction messagePOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+json
X-Transaction-Message: New Concept Scheme created.Body
{
"@id": "example:cs",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "Example concept scheme"
}Response
201Create ConceptScheme with json transaction message ¶
Create ConceptScheme with json transaction messagePOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+json
X-Transaction-Message-Json: {"templateKey": "api-test-concept-scheme-created", "params": ["example:cs"]}Body
{
"@id": "example:cs",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "Example concept scheme"
}Response
201Create ConceptScheme with invalid json transaction message ¶
Create ConceptScheme with invalid json transaction messagePOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+json
X-Transaction-Message-Json: INVALID-JSONBody
{
"@id": "example:cs",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "Example concept scheme"
}Response
400Headers
Content-Type: application/jsonBody
{
"errors": [
{
"type": "validation.requestInvalid",
"params": {
"reason": "invalid bundle message",
"itemType": "bundle message",
"itemValue": "INVALID-JSON"
},
"developerInfo": [...]
}
]
}History Recording ¶
When issuing POST/PATCH/DELETE or SPARQL update to master model you can optionally provide a record
parameter telling the application if it should write a history entry (change resource) for this
operation. If you provide this parameter for an operation on task or on directly on tch graph it
will have no effect.
Create concept scheme without creating a new change ¶
Create concept scheme without creating a new changePOST/{graphUri}/skos:ConceptScheme/rdf:instance{?record}
Example URI
POST /model:myExample-test/skos:ConceptScheme/rdf:instance?record=false
URI Parameters
- graphUri
string(required) Example: model:myExample-test- record
string(required) Example: false
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:ConceptScheme",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "ABC"
}Response
201Make a SPARQL update without creating a new change ¶
Make a SPARQL update without creating a new changePOST/{graphUri}/sparql{?record}
Example URI
POST /model:myExample-test/sparql?record=false
URI Parameters
- graphUri
string(required) Example: model:myExample-test- record
string(required) Example: false
Request
Headers
Content-Type: multipart/form-data;boundary=--ENDBody
----END
Content-Disposition: form-data; name="update"
PREFIX example: <http://proto.smartlogic.com/example#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
INSERT {
example:ConceptScheme rdf:type skos:ConceptScheme.
example:ConceptScheme rdfs:label "ConceptScheme".
}
WHERE{}
----END--Response
200URI Generation ¶
When creating new resources, you can always pass your own URI in the “@id” field. However, you can also skip this field (or provide a blank node id, which is equivalent according to JSON-LD standard). In this case the server will generate a unique URI for you. Below you will find example blueprints.
Graph ¶
Create new ConceptScheme with auto-generated URIPOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "ConceptSchemeNameForUriGeneration"
}Response
201Headers
Location: ../%3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FConceptScheme%2FConceptSchemeNameForUriGeneration%3E
x-location-uri: %3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FConceptScheme%2FConceptSchemeNameForUriGeneration%3ECreate a concept that is a child of a concept schemePOST/{graphUri}
Example URI
POST /task:myExample:test
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@type": [
"skos:Concept"
],
"skos:topConceptOf": {
"@id": "example:Topics"
},
"skosxl:prefLabel": [
{
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks",
"@language": "en"
}
]
}
]
}Response
201Headers
Location: ../%3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FDrinks%3E
x-location-uri: %3Chttp:%2F%2Fsmartlogic.com%2Fapitest%2FDrinks%3EFiltering - Autocomplete ¶
Get concepts and concept schemes starting with "b" ¶
Get concepts and concept schemes starting with "b"GET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters,limit}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(skosxl:prefLabel/skosxl:literalForm|rdfs:label autocomplete prefix "b")&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(skosxl:prefLabel/skosxl:literalForm|rdfs:label autocomplete prefix "b")- limit
string(required) Example: 100
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:BankingSupervision",
"@type" : [ "example:ConsumerProtection", "example:LegalAndRegulatory" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Banking Supervision"
}
}, {
"@id" : "example:Brands",
"@type" : [ "skos:ConceptScheme" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Brands"
}
}, {
"@id" : "example:BritishAirwaysPLC",
"@type" : [ "example:Company" ],
"meta:displayName" : {
"@value" : "British Airways PLC"
}
} ]
}Get concept schemes starting with "b" ¶
Get concept schemes starting with "b"GET/{graphUri}/skos:ConceptScheme/rdf:instance{?properties,filters,limit}
Example URI
GET /model:myExample/skos:ConceptScheme/rdf:instance?properties=rdf:type,meta:displayName&filters=subject(autocomplete prefix "b")&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(autocomplete prefix "b")- limit
string(required) Example: 100
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [
{
"@id" : "example:Brands",
"@type" : [ "skos:ConceptScheme" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Brands"
}
}
]
}Get concepts that start with 'w' in 'en' lang ¶
Get concepts that start with 'w' in 'en' langGET/{graphUri}/skos:Concept/meta:transitiveInstance{?properties,filters,language,limit}
Example URI
GET /model:myExample-test/skos:Concept/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(autocomplete prefix "w"@en)&language=en&limit=100
URI Parameters
- graphUri
string(required) Example: model:myExample-test- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(autocomplete prefix "w"@en)- language
string(required) Example: en- limit
string(required) Example: 100
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@context": {...},
"@graph" : [ {
"@id" : "example:Warsaw",
"@type" : [ "skos:Concept" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Warsaw"
}
} ]
}Filtering - Labels ¶
Get concept schemes with prelLabel matching regex ¶
Get concept schemes with prelLabel matching regexGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(skosxl:prefLabel/skosxl:literalForm matches "(?i)labour")
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(skosxl:prefLabel/skosxl:literalForm matches "(?i)labour")
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:ChildLabour",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Child labour"
}
}, {
"@id" : "example:Labour",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Labour"
}
}, {
"@id" : "example:LabourConditions",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Labour conditions"
}
} ],
"@context" : {...}
}Get concept schemes with prelLabel matching regex/lang ¶
Get concept schemes with prelLabel matching regex/langGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(skosxl:prefLabel/skosxl:literalForm matches "Finances"@fr)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(skosxl:prefLabel/skosxl:literalForm matches "Finances"@fr)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:FinanceAndEconomics",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Finance & economics"
}
} ],
"@context" : {...}
}Filtering - Classes ¶
Get concepts having given exact class ¶
Get concepts having given exact classGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(rdf:type=example:Sector)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(rdf:type=example:Sector)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:Airlines",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Airlines"
}
}, {
"@id" : "example:ClothingRetail",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Clothing retail"
}
}, {
"@id" : "example:ConsumerDiscretionary",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Consumer discretionary"
}
}, {
"@id" : "example:ConsumerStaples",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Consumer staples"
}
}, {
"@id" : "example:FoodAndStaplesRetailing",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Food & staples retailing"
}
}, {
"@id" : "example:FoodRetail",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Food retail"
}
}, {
"@id" : "example:HealthCare",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Health care"
}
}, {
"@id" : "example:Pharmaceuticals",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Pharmaceuticals"
}
}, {
"@id" : "example:PharmaceuticalsAndBiotechnology",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Pharmaceuticals and biotechnology"
}
}, {
"@id" : "example:Retailing",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Retailing"
}
}, {
"@id" : "example:Telecommunications",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Telecommunications"
}
}, {
"@id" : "example:Transportation",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Transportation"
}
} ],
"@context" : {...}
}Get concepts having given class, including subclasses ¶
Get concepts having given class, including subclassesGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(rdf:type/rdfs:subClassOf*=example:Topic)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(rdf:type/rdfs:subClassOf*=example:Topic)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:BankingSupervision",
"@type" : [ "example:ConsumerProtection", "example:LegalAndRegulatory" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Banking Supervision"
}
}, {
"@id" : "example:ChildLabour",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Child labour"
}
}, {
"@id" : "example:CommodityPrices",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Commodity prices"
}
}, {
"@id" : "example:Compliance",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Compliance"
}
}, {
"@id" : "example:CorporateSocialResponsibility",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Corporate Social Responsibility"
}
}, {
"@id" : "example:DataProtection",
"@type" : [ "example:Privacy", "example:Technology" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Data Protection"
}
}, {
"@id" : "example:Ethics",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Ethics"
}
}, {
"@id" : "example:FinanceAndEconomics",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Finance & economics"
}
}, {
"@id" : "example:Labour",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Labour"
}
}, {
"@id" : "example:LabourConditions",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Labour conditions"
}
}, {
"@id" : "example:LawAndRegulation",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Law & regulation"
}
}, {
"@id" : "example:MedicalNegligence",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Medical negligence"
}
}, {
"@id" : "example:Negligence",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Negligence"
}
}, {
"@id" : "example:OilPrices",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Oil prices"
}
}, {
"@id" : "example:Patents",
"@type" : [ "example:Topic" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Patents"
}
} ],
"@context" : {...}
}Get concepts having multiple given classes ¶
Get concepts having multiple given classesGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(rdf:type=example:ConsumerProtection),subject(rdf:type=example:LegalAndRegulatory)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(rdf:type=example:ConsumerProtection),subject(rdf:type=example:LegalAndRegulatory)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:BankingSupervision",
"@type" : [ "example:ConsumerProtection", "example:LegalAndRegulatory" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Banking Supervision"
}
} ],
"@context" : {...}
}Filtering - Relations ¶
Get concepts having given relation ¶
Get concepts having given relationGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(skos:related=example:FoodRetail)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(skos:related=example:FoodRetail)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:Retailing",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Retailing"
}
}, {
"@id" : "example:Transportation",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Transportation"
}
} ],
"@context" : {...}
}Get concepts having given relation, including sub-properties ¶
Get concepts having given relation, including sub-propertiesGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(?related=example:FoodRetail),related(rdfs:subPropertyOf*=skos:related)
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(?related=example:FoodRetail),related(rdfs:subPropertyOf*=skos:related)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:TescoPLC",
"@type" : [ "example:Company" ],
"meta:displayName" : {
"@value" : "Tesco PLC"
}
}, {
"@id" : "example:Retailing",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Retailing"
}
}, {
"@id" : "example:Transportation",
"@type" : [ "example:Sector" ],
"meta:displayName" : {
"@language" : "en",
"@value" : "Transportation"
}
} ],
"@context" : {...}
}Filtering - Full Search ¶
Get concepts that contain string matching wildcard pattern ¶
Get concepts that contain string matching wildcard patternGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName&filters=subject(anythingContains "a?t*PLC")
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName- filters
string(required) Example: subject(anythingContains "a?t*PLC")
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:AstraZenecaPLC",
"@type" : [ "example:Company" ],
"meta:displayName" : {
"@value" : "AstraZeneca PLC"
}
} ],
"@context" : {...}
}Get concepts matching wildcard pattern ¶
Get concepts matching wildcard patternGET/{graphUri}/skos:Concept,skos:ConceptScheme/meta:transitiveInstance{?properties,filters}
Example URI
GET /model:myExample/skos:Concept,skos:ConceptScheme/meta:transitiveInstance?properties=rdf:type,meta:displayName,skosxl:altLabel/skosxl:literalForm&filters=subject(anythingMatches "^Si")
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(required) Example: rdf:type,meta:displayName,skosxl:altLabel/skosxl:literalForm- filters
string(required) Example: subject(anythingMatches "^Si")
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "example:TerrenceLeahy",
"@type" : [ "example:Executive" ],
"meta:displayName" : {
"@value" : "Terrence Leahy"
},
"skosxl:altLabel" : [ {
"@id" : "example:SirTerrence_",
"skosxl:literalForm" : [ {
"@value" : "Sir Terrence"
} ]
}, {
"@id" : "example:SirTerrenceLeahy_",
"skosxl:literalForm" : [ {
"@value" : "Sir Terrence Leahy"
} ]
}, {
"@id" : "example:TerryLeahy_",
"skosxl:literalForm" : [ {
"@value" : "Terry Leahy"
} ]
} ]
} ],
"@context" : {...}
}Filtering - Changes ¶
Changes ¶
Get changes by given authorGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=meta:transactionMessage&sort=dcterms:created&filters=subject(sioc:has_creator=user:Administrator)
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: meta:transactionMessage- sort
string(required) Example: dcterms:created- filters
string(required) Example: subject(sioc:has_creator=user:Administrator)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage" : {
"@value" : "New Concept Scheme created."
}
}],
"@context": {...}
}Get changes of skos:broaderGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=meta:transactionMessage&sort=dcterms:created&filters=subject((teamwork:added|teamwork:deleted)/teamwork:predicate=skos:broader)
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: meta:transactionMessage- sort
string(required) Example: dcterms:created- filters
string(required) Example: subject((teamwork:added|teamwork:deleted)/teamwork:predicate=skos:broader)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value" : "broader added"
}
} ],
"@context": {...}
}Get changes for all ConceptsGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:${api.model.id}:${api.test.id}/teamwork:Change/rdf:instance?properties=meta:transactionMessage&sort=dcterms:created&filters=subject(sem:about/rdf:type/rdfs:subClassOf*=skos:Concept)
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.test.id}- properties
string(required) Example: meta:transactionMessage- filters
string(required) Example: subject(sem:about/rdf:type/rdfs:subClassOf*=skos:Concept)- sort
string(required) Example: dcterms:created
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "Warsaw created"
}
}, {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "London created"
}
} ],
"@context": {...}
}Get changes by time rangeGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=sem:about,dcterms:created&sort=dcterms:created&filters=subject(dcterms:created > "2015-10-28T12:46:09.144Z"^^xsd:dateTime)
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: sem:about,dcterms:created- sort
string(required) Example: dcterms:created- filters
string(required) Example: subject(dcterms:created > "2015-10-28T12:46:09.144Z"^^xsd:dateTime)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"dcterms:created" : [ {
"@type" : "xsd:dateTime",
"@value" : "!/{\"type\": \"string\"}/!"
} ],
"sem:about" : [ {
"@id" : "example:GET.filterChangesByDate:cs1"
} ]
} ],
"@context": {...}
}Changes without languageGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:${api.model.id}:${api.test.id}/teamwork:Change/rdf:instance?properties=meta:transactionMessage&sort=dcterms:created&filters=subject((teamwork:added|teamwork:deleted)/teamwork:object contains "*"@)
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.test.id}- properties
string(required) Example: meta:transactionMessage- filters
string(required) Example: subject((teamwork:added|teamwork:deleted)/teamwork:object contains "*"@)- sort
string(required) Example: dcterms:created
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "First scheme created"
}
}, {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "Second scheme created"
}
} ],
"@context": {...}
}Get changes for given resourceGET/sys/{graphUri}/teamwork:Change/rdf:instance{?properties,sort,filters}
Example URI
GET /sys/task:myExample:test/teamwork:Change/rdf:instance?properties=meta:transactionMessage&sort=dcterms:created&filters=subject(sem:about=example:cs1)
URI Parameters
- graphUri
string(required) Example: task:myExample:test- properties
string(required) Example: meta:transactionMessage- sort
string(required) Example: dcterms:created- filters
string(required) Example: subject(sem:about=example:cs1)
Response
200Headers
Content-Type: application/ld+jsonBody
{
"@graph" : [ {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "First scheme created"
}
}, {
"@id" : "%/^urn:x-change:/%",
"meta:transactionMessage": {
"@value": "First scheme modified"
}
} ],
"@context": {...}
}SPARQL Endpoints ¶
API users can use SPARQL to query, add, remove or update information in the system.
Each graph can be used as a SPARQL endpoint simply by adding ‘sparql’ to its uri, i.e.
/api/{graphUri}/sparql. Endpoints support both selects
and updates.
Parameters
All SPARQL endpoints support checkConstraints and runEditRules parameters. Those parameters
alter the way updates are performed:
-
checkConstraints- iftrueconstraints will be checked after query is performed. Whole query will be rejected if constraints would be broken by executing the query. -
runEditRules- iftrueadditional edit rules will be executed after query, e.g. creating missing GUID.
Both checkConstraints and runEditRules are turned on by default. Turning them off can cause
data corruption and should be done with care.
Examples
Submit invalid update with checkConstraints ¶
Submit invalid update with checkConstraintsPOST/model:myExample/sparql{?checkConstraints}
Example URI
POST /model:myExample/sparql?checkConstraints=true
URI Parameters
- checkConstraints
boolean(optional) Default: true Example: true
Request
Headers
Content-Type: multipart/form-data;boundary=--ENDBody
----END
Content-Disposition: form-data; name="update"
PREFIX example: <http://proto.smartlogic.com/example#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
INSERT {
example:exampleConceptScheme a skos:ConceptScheme .
example:exampleConceptScheme rdfs:label "firstLabel"@en.
example:exampleConceptScheme rdfs:label "secondLabel"@en.
}WHERE{}
----END--Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"type": "consistency.constraint",
"params": {
"constraintId": "N005",
"level": "Error",
"message": "Concept Scheme can only have one label per language (@en), found 1 violation(s).",
"path": "rdfs:label",
"root": "example:exampleConceptScheme",
"value": "firstLabel@en"
},
"developerInfo": [...]
},
{
"type": "consistency.constraint",
"params": {
"constraintId": "N005",
"level": "Error",
"message": "Concept Scheme can only have one label per language (@en), found 1 violation(s).",
"path": "rdfs:label",
"root": "example:exampleConceptScheme",
"value": "secondLabel@en"
},
"developerInfo": [...]
}
]
}Submit update with runEditRules ¶
Submit update with runEditRulesPOST/{graphUri}/sparql{?runEditRules}
Example URI
POST /model:myExample-test/sparql?runEditRules=true
URI Parameters
- graphUri
string(required) Example: model:myExample-test- runEditRules
boolean(optional) Default: true Example: true
Request
Headers
Content-Type: multipart/form-data;boundary=--ENDBody
----END
Content-Disposition: form-data; name="update"
PREFIX example: <http://proto.smartlogic.com/example#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
INSERT {
example:ConceptScheme rdf:type skos:ConceptScheme.
example:ConceptScheme rdfs:label "ConceptScheme".
}
WHERE{}
----END--Response
200Get number of concepts ¶
Get number of conceptsGET/model:myExample/sparql{?query}
Example URI
GET /model:myExample/sparql?query=PREFIX skos: SELECT (count(distinct(?s)) AS ?abc) (count(?o) AS ?cnt) WHERE {?s skos:hasTopConcept ?o}
URI Parameters
- query
string(required) Example: PREFIX skos: <http://www.w3.org/2004/02/skos/core#> SELECT (count(distinct(?s)) AS ?abc) (count(?o) AS ?cnt) WHERE {?s skos:hasTopConcept ?o}
Request
Headers
Accept: text/csvResponse
200Headers
Content-Type: text/csvBody
abc,cnt
5,23add skos:note using SPARQL ¶
add skos:note using SPARQLPOST/model:myExample-test/sparql
Example URI
POST /model:myExample-test/sparql
Request
Headers
Content-Type: multipart/form-data;boundary=--ENDBody
----END
Content-Disposition: form-data; name="update"
PREFIX example: <http://proto.smartlogic.com/example#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
INSERT {
example:Geography skos:note "Note added by SPARQL" .
}
WHERE {}
----END--Response
200Asynchronous Request Processing ¶
Asynchronous request processing allows to execute action associated with a request, while the request itself ends just after its payload is submitted.
This option can be particularly useful in case of long-running requests, which might be timed-out by a proxy server. For example, an import request may take significantly longer, due to model post-processing, than model upload itself.
Job scheduling
In order to schedule an asynchronous request processing, add async request parameter with
value true. Then, a new asynchronous job, with its identifier and status, is created.
The response status for the scheduling request is 202. The response body contains the job
identifier, under jobId field in the response body JSON. Also, the response includes the
Location header pointing to the URI which should be used to track the request processing.
Note: All types of requests can be processed asynchronously, including GET, POST, PATCH.
Job status
An asynchronous job can be tracked under /async/jobs/{jobId} URI. The job status is
returned under status field in response body JSON.
The following asynchronous job statuses are supported:
-
ACCEPTED - successful job scheduling
-
RUNNING - being processed
-
ERROR - job processing failed
-
FINISHED - job processing is finished
-
CANCELLED - job processing is cancelled
Additionally, response body JSON, for a job with status RUNNING may include progress
field with additional progress information.
Job result
Once an asynchronous job is completed (with status ERROR or FINISHED), job result is available.
It can be retrieved from /async/jobs/{jobId}/result URI. In case of a completed job,
the URI is provided in the response Link header, to the request fetching job status.
Job status and result are available for a certain amount time, since completion, by default, 30min.
Job lifetime can be controlled by a client by adding an optional resultLifetime parameter
(expressed in milliseconds), to the request scheduling a job.
Job cancelling
In order to cancel a running asynchronous job, send DELETE to URI: /async/jobs/{jobId}.
Note: cancelling does not interrupt the thread executing given job. However, the underlying code
may lookup the job status and stop execution.
Import example ¶
The following example demonstrates the use of asynchronous request processing in case of import.
SchedulePOST/backup/{graphUri}/import{?async}
Example URI
POST /backup/task:myExample:test/import?async=true
URI Parameters
- graphUri
string(required) Example: task:myExample:test- async
string(required) Example: true
Request
Headers
Content-Type: multipart/form-data;boundary=----END
X-ApiTestHook-SaveFromBody: __ASYNC_JOB_ID__:(body) => (JSON.parse(body)["jobId"] || JSON.parse(body)["files"][0]["id"])
X-Expect-Uri-RelativeTo: ApiEndpointBody
------END
Content-Disposition: form-data; name="format"
turtle
------END
Content-Disposition: form-data; name="file"
# baseURI: http://proto.smartlogic.com/example
@prefix example: <http://proto.smartlogic.com/example#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix skosxl: <http://www.w3.org/2008/05/skos-xl#> .
@prefix sem: <http://www.smartlogic.com/2014/08/semaphore-core#> .
<http://proto.smartlogic.com/example>
rdf:type owl:Ontology
.
example:Cities
rdf:type skos:ConceptScheme
.
example:Warsaw
rdf:type skos:Concept
.
------END--Response
202Headers
Content-Type: application/json
Location: ../../async/jobs/__ASYNC_JOB_ID__Body
{
"status": "ACCEPTED"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ACCEPTED"
]
}
},
"required": [
"status"
]
}JobGET/async/jobs/{jobId}
Example URI
GET /async/jobs/__ASYNC_JOB_ID__
URI Parameters
- jobId
string(required) Example: __ASYNC_JOB_ID__
Request
Headers
X-Expect-Uri-RelativeTo: ApiEndpoint
X-ApiTestHook-WaitForMatchingResponse: (body) => JSON.parse(body).statusResponse
200Headers
Content-Type: application/json
Link: <./__ASYNC_JOB_ID__/result>; rel="result"; title="Job result"Body
{
"jobId": "%/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}-[0-9]+$/%",
"status": "FINISHED",
"resultLifetimeMs": 1800000,
"creationTimeMs": "!/{\"type\": \"integer\"}/!",
"completedAfterMs": "!/{\"type\": \"integer\"}/!",
"nextStatusCheckMs": "!/{\"type\": \"integer\"}/!"
}ResultGET/async/jobs/{jobId}/result
Example URI
GET /async/jobs/__ASYNC_JOB_ID__/result
URI Parameters
- jobId
string(required) Example: __ASYNC_JOB_ID__
Response
200Headers
Content-Type: application/jsonBody
{
"message": "File with 2 statements has been imported successfully.",
"notes": []
}Location and Link ¶
Location and Link
Two standard headers are used to indicate resource URI in response: Location and Link.
The Location header is returned in response to a request which creates a new resource
(see rfc7231), for example, to a request creating a new
concept scheme.
The Link header is returned in response to indicate a connection between the requested
resource and another resource (see rfc5988). For example,
Link header is returned to a GET request checking asynchronous job status, when the job is
FINISHED In that case, Link indicates URI from which the job result can be fetched.
Note that, the job result is not indicated by Location header, as the request does not
create a new resource - the resource representing job result was created asynchronously, as
an effect of the first request, scheduling asynchronous job.
By default, URI returned in the Location and Link headers is absolute, but the
behaviour can be configured, per deployment, by setting Java system property:
com.smartlogic.uri.relativeTo, which can have one of the values:
-
Absolute- absolute URI -
ApiEndpoint- URI relative to API endpoint
Examples ¶
LocationPOST/{graphUri}/skos:ConceptScheme/rdf:instance
Example URI
POST /task:myExample:test/skos:ConceptScheme/rdf:instance
URI Parameters
- graphUri
string(required) Example: task:myExample:test
Request
Headers
Content-Type: application/ld+json
X-Expect-Uri-RelativeTo: ApiEndpointBody
{
"@id": "example:ABC",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": "ABC"
}Response
201Headers
Location: ../example:ABC
X-Location-Uri: example:ABCLinkGET/async/jobs/{jobId}
Example URI
GET /async/jobs/__ASYNC_JOB_ID__
URI Parameters
- jobId
string(required) Example: __ASYNC_JOB_ID__
Request
Headers
X-ApiTestHook-WaitForMatchingResponse: (body) => JSON.parse(body).status
X-Expect-Uri-RelativeTo: ApiEndpointResponse
200Headers
Content-Type: application/json
Link: <./__ASYNC_JOB_ID__/result>; rel="result"; title="Job result"Body
{
"status": "FINISHED"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"FINISHED"
]
}
},
"required": [
"status"
]
}Error Handling ¶
API Error response format
If an error occurred during the request processing the response should contain errors field:
{
...
errors: {/*errors list here*/}
}Each error entry should always contain:
-
type - a key to get error message template on client side
-
params - object containing parameters to fill the error message template
-
developerInfo - special key containing an object with more verbose information for developer:
- stackTrace - server stack trace
- envVars - environment variables list
Example of error response:
{
...
errors: [
{
type: "server.database.connection.connectionError",
params: {
connectionPort: "7000",
user: "adam"
}
developerInfo: {
/*verbose info for developer*/
}
}
]
}We can handle more errors sharing the same http code (e.g. validation)
{
errors: [
{
type: "validation.invalidValue",
params: {
fieldName: "modelName"
}
},
{
type: "validation.tooShort",
params: {
fieldName: "modelName"
}
}
]
}We would like to give as specific error message as possible, so the error type structure will be a dot separated list of error subtypes leading from less specific to more specific cause of the problem. We will have three general categories (areas) of errors:
-
validation
-
authorization
-
server
First error subtype should be one of above. Each error type can contain four subtypes maximum. For multiword error subtypes we use camelcase. Same refers to the key names in errors[].params.
Error Handling - Constraints ¶
Constraints are a special category of errors, returned when one or more spin constraints are violated
as a result of performing update operation. Each constraint has a level - either error or warning.
Error level constraint violations are considered fatal and are never allowed.
Warning level constraint violations are also normally not allowed, however a special parameter
warningsAccepted=true can be passed to disregard the violation and save the change to graph anyway.
In this case an operation succeeds with normal 2xx error code, but the constraint violations are
still returned in response using JSON payload with “warnings” key in it.
Concept Scheme ¶
Remove last labelPATCH/{graphUri}/{conceptSchemeUri}{?warningsAccepted}
Example URI
PATCH /task:${api.model.id}:${api.test.id}/${api.test.prefix}:Topics?warningsAccepted=
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.test.id}- conceptSchemeUri
string(required) Example: ${api.test.prefix}:Topics- warningsAccepted
string(optional)
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "en"
}
},
{
"op": "remove",
"path": "@graph/0/rdfs:label/0"
}
]Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"type":"consistency.constraint",
"params": {
"constraintId": "N001",
"level": "Error",
"path":"rdfs:label",
"root":"example:Topics",
"message":"There should be at least one name for the Concept Scheme"
}
}
]
}Remove last label with warningsAccepted=truePATCH/{graphUri}/{conceptSchemeUri}{?warningsAccepted}
Example URI
PATCH /task:${api.model.id}:${api.test.id}/${api.test.prefix}:Topics?warningsAccepted=true
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.test.id}- conceptSchemeUri
string(required) Example: ${api.test.prefix}:Topics- warningsAccepted
string(required) Example: true
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "en"
}
},
{
"op": "remove",
"path": "@graph/0/rdfs:label/0"
}
]Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"constraintId": "N001",
"message": "There should be at least one name for the Concept Scheme",
"level": "Error",
"root": "example:Topics",
"path": "rdfs:label"
},
"type": "consistency.constraint"
}
]
}Try to add duplicate label with warningsAccepted flagPATCH/{graphUri}/{conceptSchemeUri}{?warningsAccepted}
Example URI
PATCH /task:${api.model.id}:${api.test.id}/${api.test.prefix}:Topics?warningsAccepted=true
URI Parameters
- graphUri
string(required) Example: task:${api.model.id}:${api.test.id}- conceptSchemeUri
string(required) Example: ${api.test.prefix}:Topics- warningsAccepted
string(required) Example: true
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "pl"
}
},
{
"op": "replace",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Topics",
"@language": "en"
}
}
]Response
200Body
{
"warnings": [
{
"type": "consistency.alreadyExists",
"params": {
"operationIndex": 1,
"existingModel": {
"@graph": [
{
"rdfs:label": [
{
"@value": "Topics",
"@language": "en"
}
],
"@id": "example:Topics"
}
],
"@context": {...}
}
},
"developerInfo": [...]
}
]
}Error Handling - Concept Schemes ¶
All Concept Schemes ¶
Get concept scheme for unknown modelGET/{graphUri}/skos:ConceptScheme/rdf:instance
Example URI
GET /model:myExample/skos:ConceptScheme/rdf:instance
URI Parameters
- graphUri
string(required) Example: model:myExample
Response
404Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"itemType": "model",
"itemValue": "model:UnknownModel"
},
"type": "validation.notFound"
}
]
}Single Concept Scheme ¶
Create new ConceptScheme in unknown modelPOST/{graphUri}/
Example URI
POST /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:ConceptScheme3",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": [
"ABC"
]
}Response
404Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"itemType": "tch graph",
"itemValue": "model:UnknownModel.tch"
},
"type": "validation.notFound"
}
]
}Add concept schemes with duplicate labelsPOST/task:myExample:test
Example URI
POST /task:myExample:test
Request
Headers
Content-Type: application/ld+jsonBody
{
"@graph": [
{
"@id": "example:Topics1",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": [
{
"@value": "Topics.English",
"@language": "en"
}
]
},
{
"@id": "example:Topics2",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": [
{
"@value": "Topics"
}
]
},
{
"@id": "example:Topics3",
"@type": [
"skos:ConceptScheme"
],
"rdfs:label": [
{
"@value": "Topics",
"@language": "fr"
},
{
"@value": "Topics.English",
"@language": "en"
}
]
}
]
}Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"constraintId": "N006",
"message": "In each language Concept Scheme names should be unique (@en).",
"level": "Error",
"root": "example:Topics1",
"path": "rdfs:label",
"value": "Topics.English@en"
},
"type": "consistency.constraint"
},
{
"developerInfo": [...],
"params": {
"constraintId": "N006",
"message": "In each language Concept Scheme names should be unique (@).",
"level": "Error",
"root": "example:Topics2",
"path": "rdfs:label",
"value": "Topics"
},
"type": "consistency.constraint"
},
{
"developerInfo": [...],
"params": {
"constraintId": "N006",
"message": "In each language Concept Scheme names should be unique (@en).",
"level": "Error",
"root": "example:Topics3",
"path": "rdfs:label",
"value": "Topics.English@en"
},
"type": "consistency.constraint"
},
{
"developerInfo": [...],
"params": {
"constraintId": "N006",
"message": "In each language Concept Scheme names should be unique (@fr).",
"level": "Error",
"root": "example:Topics3",
"path": "rdfs:label",
"value": "Topics@fr"
},
"type": "consistency.constraint"
}
]
}Add a label, expect constraint as the second en label is not allowedPATCH/{graphUri}/
Example URI
PATCH /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/rdfs:label/-",
"value": {
"@value": "Topics2",
"@language": "en"
}
}
]Response
409Body
{"errors": [{
"developerInfo": [...],
"type": "consistency.constraint",
"params": {
"constraintId": "N005",
"path": "rdfs:label",
"level": "Error",
"root": "example:Topics",
"value": "Topics@en",
"message": "Concept Scheme can only have one label per language (@en), found 1 violation(s)."
}
}, {
"developerInfo": [...],
"type": "consistency.constraint",
"params": {
"constraintId": "N005",
"path": "rdfs:label",
"level": "Error",
"root": "example:Topics",
"value": "Topics2@en",
"message": "Concept Scheme can only have one label per language (@en), found 1 violation(s)."
}
}]}Replace label - wrong old valuePATCH/{graphUri}/
Example URI
PATCH /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "Unknown Topics",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/rdfs:label/0",
"value": {
"@value": "New Topics",
"@language": "en"
}
}
]Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"operationIndex": 0,
"expectedModel": {
"@context": {...},
"@graph": [
{
"@id": "example:Topics",
"rdfs:label": [
{
"@value": "Unknown Topics",
"@language": "en"
}
]
}
]
},
"notFoundModel": {
"@context": {...},
"@graph": [
{
"@id": "example:Topics",
"rdfs:label": [
{
"@value": "Unknown Topics",
"@language": "en"
}
]
}
]
}
},
"type": "consistency.missing.model"
}
]
}Delete an empty Concept SchemeDELETE/{graphUri}/{?properties,mode}
Example URI
DELETE /model:myExample/?properties=&mode=empty
URI Parameters
- graphUri
string(required) Example: model:myExample- properties
string(optional)- mode
string(required) Example: empty
Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"type": "consistency.constraint",
"params": {
"constraintId": "N007",
"level": "Error",
"message": "Concept should be attached to the hierarchy",
"root": "example:Warsaw"
},
"developerInfo": [...]
}
]
}Error Handling - Concepts ¶
Single Concept ¶
Add skos:scopeNote metadata with empty valuePOST/{graphUri}/
Example URI
POST /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Warsaw",
"skos:scopeNote": [
""
]
}Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"type": "validation.property.hasEmptyValue",
"params": {
"itemType": "property",
"itemValue": "skos:scopeNote"
}
}
]}Create second concept with the same labelPOST/{graphUri}/
Example URI
POST /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/ld+jsonBody
{
"@id": "example:Drinks2",
"@type": [
"example:Drink"
],
"skos:topConceptOf": {
"@id": "example:Topics"
},
"skosxl:prefLabel": [
{
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": [
{
"@value": "Drinks",
"@language": "en"
}
]
}
]
}Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"constraintId": "CUST002",
"path": "skosxl:prefLabel",
"level": "Warning",
"root": "example:Drinks2",
"message": "Two concepts must have different pref labels.",
"value": "Drinks@en"
},
"type": "consistency.constraint"
}
]
}Add duplicate altLabelPATCH/{graphUri}/
Example URI
PATCH /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "add",
"path": "@graph/0/skosxl:altLabel/-",
"value": {
"@id": "example:Label",
"@type": [
"skosxl:Label"
],
"skosxl:literalForm": {
"@value": "Drinkz",
"@language": "en"
}
}
}
]Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"operationIndex": 0,
"existingModel": {
"@context": {...},
"@graph": [{
"skosxl:altLabel": [{
"@type": ["skosxl:Label"],
"@id": "example:Label",
"skosxl:literalForm": [{
"@value": "Drinkz",
"@language": "en"
}]
}],
"@id": "example:Drinks"
}]
}
},
"type": "consistency.alreadyExists"
}
]
}Replace non-existing literalForm of prefLabelPATCH/{graphUri}/
Example URI
PATCH /model:myExample/
URI Parameters
- graphUri
string(required) Example: model:myExample
Request
Headers
Content-Type: application/json-patch+jsonBody
[
{
"op": "test",
"path": "@graph/0/skosxl:literalForm/0",
"value": {
"@value": "Drinks non existing",
"@language": "en"
}
},
{
"op": "replace",
"path": "@graph/0/skosxl:literalForm/0",
"value": {
"@value": "DrinksALL"
}
}
]Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"developerInfo": [...],
"params": {
"operationIndex": 0,
"expectedModel": {
"@context": {...},
"@graph": [{
"skosxl:literalForm": [{
"@value": "Drinks non existing",
"@language": "en"
}],
"@id": "example:TopicsLabel1"
}]
},
"notFoundModel": {
"@context": {...},
"@graph": [{
"skosxl:literalForm": [{
"@value": "Drinks non existing",
"@language": "en"
}],
"@id": "example:TopicsLabel1"
}]
}
},
"type": "consistency.missing.model"
}
]
}Delete using mode=emptyDELETE/{graphUri}/{conceptUri}{?mode}
Example URI
DELETE /task:myExample:test/example:Warsaw?mode=empty
URI Parameters
- graphUri
string(required) Example: task:myExample:test- conceptUri
example:London(required) Example: example:Warsaw- mode
string(required) Example: empty
Response
409Headers
Content-Type: application/jsonBody
{
"errors": [
{
"type": "consistency.constraint",
"params": {
"constraintId": "N007",
"level": "Error",
"message": "Concept should be attached to the hierarchy",
"root": "example:Bielany"
},
"developerInfo": [...]
}
]
}
Comments ¶
Add post in task ¶
/sys/{graphUri}/sioc:Post/rdf:instanceExample URI
string(required) Example: task:myExample-test:task1Headers
Content-Type: application/ld+jsonBody
{ "@id": "example:Comment22", "@type": [ "sioc:Post" ], "sioc:about": { "@id": "example:Warsaw" }, "rdfs:comment": "comment in task", "teamwork:postStatus": { "@id": "teamwork:PostStatusDeclined" } }201