Archive 1.x:Ontology Update/1.1

From OSF Wiki
Jump to: navigation, search
Ontology: Update endpoint version:
1.1
2
3

The Ontology Update service is used to update an OWL ontology existing in the OSF Web Service instance.

This service is a web service wrapper over the OWLAPI ontology library. It wraps all the needed functionalities related to updating an ontology. Most of the related API has been implemented. So we can say that web service (with the other related services) turns the OWLAPI into a web service API.

There is an important semantic distinction to do: this endpoint is about UPDATING an ontology. This means that we may be updating ontologies resources, or creating new ones. The logic is that by creating new resources (such as classes, properties and named individuals) we are updating the ontology.

This is what this web service endpoint is about. To update or create an existing resource, the requester only has to send the RDF description of that resource to update or create. If the resource is existing, it will get updated, if it is not, it will get added.

Developers communicate with the Ontology Update Web service using the HTTP POST method. You may request one of the following mime types: (1) text/xml, (2) application/rdf+xml, (3) application/rdf+n3 or (4) application/json. The content returned by the Web service is serialized using the mime type requested and the data returned depends on the parameters selected.

Version

This documentation page is used for the version 1.1 of this endpoint. Check at the top of this page to see the documentation pages for the other versions of this endpoint.

Usage

This Web service is intended to be used by content management systems, developers or administrators to update ontologies that are hosted on a OSF Web Service instance, and that are used to describe the named entities in the system.

This endpoint, along with the other related endpoints: Ontology Read, Ontology Create and Ontology Delete; can be seen as the brain of your OSF Web Service instance.

Web Service Endpoint Information

This section describes all the permissions you need in the WSF (Web Service Framework) to send a query to this Web service endpoint, and it describes how to access it.

To access this Web service endpoint you need the proper CRUD (Create, Read, Update and Delete) permissions on a specific graph (dataset) of the WSF. Without the proper permissions on this graph you won't be able to send any queries to the endpoint.

Needed registered CRUD permission:
  • Create: True
  • Read: False
  • Update: True
  • Delete: False

As shown on the graph URI:

  • URI of the dataset being updated

Note: normally, the URI of an Ontology dataset is the URL used to import that ontology in the system. The URL can be the URI of the ontology if it was resolvable on the Web, or the URL where the OWL file, containing the ontology's description, can be resolved by the server (on the web, on the file system, etc) via a URL.

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline Web services may not offer other values than the default.

HTTP method:
  • POST

Possible "Accept:" HTTP header field value:

  • text/xml (structXML)
  • application/json (structJSON)
  • application/rdf+xml (RDF+XML)
  • application/rdf+n3 (N3/Turtle)
  • application/iron+json (irJSON)
  • application/iron+csv (commON)

URI:

  • http://[...]/ws/ontology/update/ ?ontology=param1&function=param2&parameters=param3&reasoner=param4&registered_ip=param5

URI dynamic parameters description:

Note: All parameters have to be URL-encoded

  • param1. URI of the ontology; the URI of an Ontology dataset is the URL used to import that ontology in the system. The URL can be the URI of the ontology if it was resolvable on the Web, or the URL where the OWL file, containing the ontology's description, can be resolved by the server (on the web, on the file system, etc) via a URL. If you don't know what the URI is, you can always use the getLoadedOntologies function to get the list of all loaded ontologies URI.
  • param2 The function name to use for this query. The complete list of function names and their descriptions is available below.
  • param3. The list of parameters used by the function you are about to use. The parameters are split by a ";" character. The parameter and its value are defined as param-1=value-1. This tuple has to be encoded. So, the parameters should be constructed that way in the URL: &parameters=urlencode("param-1=value-1");urlencode("param-2=value-2"). See the example below.
  • param4. Only used when advancedIndexation=true One of:
    • True (Default) — Enable the reasoner for indexing the ontology into OSF Web Service (the triple store and the full text engine)
    • False — Disable the reasoner for this query
  • param5. Target IP address registered in the WSF. Needed when param1 = "access_user". Otherwise this parameter as to be omitted.

Functions

This web service endpoint support a series of function that can be queried. All the functions are listed in the section below, along with all their parameters.

All queries are built the same way:


  • http://[...]/ws/ontology/update/ parameters: ontology=http%3A%2F%2Fsome-ontology-uri&function=saveOntology

Where:

  • ontology is the URI of the ontology to query
  • function is the name of the function to use for that query
  • parameters is a list of encoded parameters/values to give as input to that function


createOrUpdateEntity

Create or update an entity in the ontology. An entity can be anything of a class, an object property, a datatype property, an annotation property or a named individual.

Right now, the creation and the modification of an entity is simplified to writing the RDF triples describing the entity to create or update. The advantage of this method is that a system that interacts with the endpoints doesn't have to send multiple different queries to change multiple aspects of an entity. It only has to generate the code offline, and send it once to the Ontology Update web service endpoint, with the complete RDF description of the entity to update, or create, in the instance.

If an entity is being modified by some system, usually the workflow process is:

  1. The system send a query to the Ontology Read web service endpoint to get the current complete description of the entity to update
  2. The system modify the RDF description of that entity, the way it has to (by adding, removing or modifying triples)
  3. Once the modifications are done offline, the system send the resulting RDF document to the Ontology Update web service endpoint

That is the way to create or update any kind of entities in an ontology hosted in a OSF Web Service instance.

Function Parameters Parameter optional? Values Description
document No RDF Document A URLEncoded version of the RDF document describing the entity (class, property or named individual) to create or update in the ontology. The RDF can be serialized in XML or N3.
advancedIndexation Yes True (default) Advanced Indexation is enabled. This means that the ontology's description (so all the classes, properties and named individuals) will be indexed in the other data management system in OSF Web Service. This means that all the information in these ontologies will be accessible via the other endpoints such as the Search and the SPARQL web service endpoints. Enabling this option may render the creation process slower depending on the size of the created ontology.
False Advanced Indexation is disabled. This means that the ontologies will be queriable via the Ontology Read, Ontology Update, Ontology Create and Ontology Delete web service endpoints only.


updateEntityUri

Update (refactor) the URI of an existing entity. The entity can be a class, an object property, a datatype property, an annotation property or a named individual.

Function Parameters Parameter optional? Values Description
olduri No URI This is the current URI of the entity to update. This URI will be replaced by the newuri. After this query, that current URI won't be available anymore.
newuri No URI This is the new URI to define for the entity. This URI is replacing the olduri. After this query, this is the URI that will be referring to this entity.
advancedIndexation Yes True (default) Advanced Indexation is enabled. This means that the ontology's description (so all the classes, properties and named individuals) will be indexed in the other data management system in OSF Web Service. This means that all the information in these ontologies will be accessible via the other endpoints such as the Search and the SPARQL web service endpoints. Enabling this option may render the creation process slower depending on the size of the created ontology.
False Advanced Indexation is disabled. This means that the ontologies will be queriable via the Ontology Read, Ontology Update, Ontology Create and Ontology Delete web service endpoints only.


saveOntology

When the createOrUpdateEntity, or the updateEntityUri, functions are called via this web service endpoint, the ontology is tagged with a wsf:ontologyModified "true" triple that specifies that the ontology got modified in some ways.

What this saveOntology call does, is only to remove that tag (so, to remove the tag that says that the ontology got modified).

The ontology is after saved, and persisted, in the OWLAPI instance. However, if you want your system to save a hard-copy of an ontology that got modified (to reload it elsewhere), the you system will have to perform these steps:

  1. Check if the ontology got modified by checking if the wsf:OntologyModified "true" triple appears in the ontology's description after a call to the Ontology Read web service endpoint for the function getOntology: mode=description.
  2. If is has been modified, then it calls the Ontology Read endpoints again, but using the getSerialized function. Once it gets the serialization form of the ontology, the system can now save it on its local file system, or elsewhere.
  3. Finally it calls the saveOntology function of the Ontology Update web service endpoint to mark the ontology as saved.

There is no function parameters for this function call. The ontology to update is determined by the ontology query parameter.

HTTP Status Codes

Here are the possible HTTP status (error) codes returned by this Web service endpoint.

On error code and the specific error, a different message description can be issued (meaning a different error has been returned).

  • Code:200
    • Message: OK
  • Code:400
    • Message: Bad Request
    • Message description: No Ontology URI defined for this request
    • Message description: The function call being requested is unknown or unsupported by this Ontology Read web service endpoint
    • Message description: You forgot to mention the oldUri parameter for this update request
    • Message description: You forgot to mention the newUri parameter for this update request
    • Message description: The ontology can't be loaded by the endpoint
    • Message description: Can't parse the specified RDF document
    • Message description: No requester IP available
    • Message description: No Web service URI available
    • Message description: Target Web service XYZ not registered to this Web Services Framework
    • Message description: No access defined for this requester IP XYZ, dataset (XYZ) and Web service (XYZ)
    • Message description: The target Web service (XYZ) needs read access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)
  • Code:406
    • Message: Not Acceptable
    • Message description: Unacceptable mime type requested
  • Code:500
    • Message:Internal Error