Skip to content
Carlos Rueda edited this page Oct 27, 2016 · 15 revisions

Some manual interaction

For the test specification see here.

NOTE

  • The interaction described below was done for development purposes. For user-oriented documentation of the REST API, see https://mmisw.org/orrdoc/api/ and the documentation of particular instances liked from there.
  • The specific parameters and operations used below may have changed since the time this exercise was captured. Please let us know about any questions regarding the API. For any missing of unclear aspects, please review the corresponding issue tracker at https://github.com/mmisw/mmiorr-docs/issues (feel free to enter issues there as necessary).

Exercise performed on the command line using HTTPie. Except for ontology resolution (that can be dispatched in different formats), all API interaction is mostly JSON-oriented: the orr-ont service is mainly intended to be used by applications (not end-users).

Users

Get users:

(if not already in the database, the 'admin' user is automatically created when orr-ont starts)

$ http get :8081/api/v0/user
HTTP/1.1 200 OK
Content-Length: 58
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

[
    {
        "registered": "2015-01-01T02:09:53Z",
        "userName": "admin"
    }
]

Create a user:

$ http -a admin:admpw post :8081/api/v0/user userName=calvin firstName=Cal lastName=Vin password=hobbes
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=1las7tn57t38llnd5rl0hzw7g;Path=/
Transfer-Encoding: chunked

{
    "registered": "2015-01-01T02:14:29Z",
    "userName": "calvin"
}

Get all users:

$ http get :8081/api/v0/user
HTTP/1.1 200 OK
Content-Length: 116
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

[
    {
        "registered": "2015-01-01T02:09:53Z",
        "userName": "admin"
    },
    {
        "registered": "2015-01-01T02:14:29Z",
        "userName": "calvin"
    }
]

Get a user:

$ http get :8081/api/v0/user/calvin
HTTP/1.1 200 OK
Content-Length: 80
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

{
    "ontUri": "http://ont1",
    "registered": "2015-01-01T02:14:29Z",
    "userName": "calvin"
}

Organizations

Create an organization:

$ http -a admin:admpw post :8081/api/v0/org orgName=mmi name="mmi project"  members:='["calvin"]'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=1el864q41r9mt13dde2otjrbph;Path=/
Transfer-Encoding: chunked

{
    "orgName": "mmi",
    "registered": "2015-01-01T02:16:15Z"
}

Get all organizations:

$ http get :8081/api/v0/org
HTTP/1.1 200 OK
Content-Length: 76
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

[
    {
        "name": "mmi project",
        "orgName": "mmi",
        "registered": "2015-01-01T02:16:15Z"
    }
]

Get an organization:

$ http get :8081/api/v0/org/mmi
HTTP/1.1 200 OK
Content-Length: 74
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

{
    "name": "mmi project",
    "orgName": "mmi",
    "registered": "2015-01-01T02:16:15Z"
}

Get members of an organization:

$ http get :8081/api/v0/org/mmi/members
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)
Transfer-Encoding: chunked

{
    "members": [
        "calvin"
    ],
    "orgName": "mmi"
}

Ontologies

Register a new ontology:

$ http -a admin:admpw -f post :8081/api/v0/ont uri=http://ont1 name=example orgName=mmi userName=calvin  file@src/test/resources/test.rdf format=rdf
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=dpof8q8qqolewrjh5pp0chiy;Path=/
Transfer-Encoding: chunked

{
    "registered": "2015-01-01T02:18:12Z",
    "uri": "http://ont1",
    "version": "20141231T181812"
}

Get ontologies of a given organization:

Note: filtering mechanism for queries is very preliminary (and low priority for the time being).

$ http get :8081/api/v0/ont\?orgName=mmi
HTTP/1.1 200 OK
Content-Length: 143
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

[
    {
        "name": "self-hosted entry (renamed again5)",
        "orgName": "mmi",
        "uri": "http://localhost:8081/ont/mmi/selfhosted",
        "versions": [
            "20141231T182618"
        ]
    }
]

Register a new version of the ontology above:

$ http -a admin:admpw -f put :8081/api/v0/ont uri=http://ont1 userName=calvin file@src/test/resources/test.rdf format=rdf
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=rgxjr8i75wj21nfv0uqi7x0nf;Path=/
Transfer-Encoding: chunked

{
    "updated": "2015-01-01T02:22:56Z",
    "uri": "http://ont1",
    "version": "20141231T182256"
}
$ http get :8081/api/v0/ont
HTTP/1.1 200 OK
Content-Length: 82
Content-Type: application/json;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

[
    {
        "name": "",
        "uri": "http://ont1",
        "versions": [
            "20141231T182256",
            "20141231T181812"
        ]
    }
]

Get an ontology in a particular format:

$ http get :8081/api/v0/ont\?uri=http://ont1\&format=n3
HTTP/1.1 200 OK
Content-Length: 268
Content-Type: text/n3;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

@base          <http://ont1> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix myont: <http://localhost:8081/ont/myorg/myont/> .

<myont:hobbes>  a  <Character> .

<myont:calvin>  a        <Character> ;
        myont:hasFriend  <myont:hobbes> .

Post a self-hosted ontology:

A self-hosted ontology is simply one whose URI has the service URL as a prefix. For example, if the service is located at http://mmisw.org/ont/ then an ontology with URI http://mmisw.org/ont/myontology will be self-hosted.

$ http -a admin:admpw -f post :8081/api/v0/ont uri=http://localhost:8081/ont/mmi/selfhosted name="self-hosted entry" orgName=mmi userName=calvin file@src/test/resources/test.rdf format=rdf
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=amzk4xmjpebu1q5blyayp5taa;Path=/
Transfer-Encoding: chunked

{
    "registered": "2015-01-01T02:26:18Z",
    "uri": "http://localhost:8081/ont/mmi/selfhosted",
    "version": "20141231T182618"
}

Get a self-hosted ontology (with direct request to its URL):

$ http get http://localhost:8081/ont/mmi/selfhosted
HTTP/1.1 200 OK
Content-Length: 310
Content-Type: application/rdf+xml;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

<?xml version="1.0" ?>
<rdf:RDF xmlns:myont="http://localhost:8081/ont/myorg/myont/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
    <Character rdf:about="myont:calvin">
        <myont:hasFriend rdf:resource="myont:hobbes"/>
    </Character>
    <Character rdf:about="myont:hobbes">
    </Character>
</rdf:RDF>

#### Get self-hosted ontology in a particular format:
$ http get http://localhost:8081/ont/mmi/selfhosted\?format\=n3
HTTP/1.1 200 OK
Content-Length: 297
Content-Type: text/n3;charset=UTF-8
Server: Jetty(8.1.8.v20121106)

@base          <http://localhost:8081/ont/mmi/selfhosted> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix myont: <http://localhost:8081/ont/myorg/myont/> .

<myont:hobbes>  a  <Character> .

<myont:calvin>  a        <Character> ;
        myont:hasFriend  <myont:hobbes> .

Change name of a version of an ontology:

$ http -a admin:admpw -f put :8081/api/v0/ont uri=http://localhost:8081/ont/mmi/selfhosted version=20141231T182618 userName=calvin name="self-hosted entry (renamed)"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=1169sqb2i02kyfvl5l0vith6i;Path=/
Transfer-Encoding: chunked

{
    "updated": "2015-01-01T02:26:18Z",
    "uri": "http://localhost:8081/ont/mmi/selfhosted",
    "version": "20141231T182618"
}

Unregister a particular ontology version:

$ http -a admin:admpw delete :8081/api/v0/ont\?uri=http://ont1\&version=20141231T181812\&userName=calvin
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=1orei8lwy7odz4799is90nzia;Path=/
Transfer-Encoding: chunked

{
    "removed": "2015-01-01T02:31:12Z",
    "uri": "http://ont1",
    "version": "20141231T181812"
}

Unregister whole ontology entry:

(just omit the version parameter)

$ http -a admin:admpw delete :8081/api/v0/ont\?uri=http://ont1\&userName=calvin
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Expires: Thu, 01 Jan 1970 00:00:00 GMT
REMOTE_USER: admin
Server: Jetty(8.1.8.v20121106)
Set-Cookie: JSESSIONID=ioyndg7035sejynjtql99hih;Path=/
Transfer-Encoding: chunked

{
    "removed": "2015-01-01T02:32:25Z",
    "uri": "http://ont1"
}