The input and output of RESTful services are also to a certain extend free-format, similar to the free format of JSON objects. The purpose of the ontology with regard to RESTful services is to provide machine readable and standard documentation of each of the services provided by JThermodynamicsCloud. A POST to a RESTful service, as used by JThermodynamicsCloud, sends JSON data to the server and with this information performs a task and sends a response, also a JSON object, back to the client. JSON objects are, in general, free-format, so they can be of any property-value pair, where the value can be a simple data object like a string or a nested object like another JSON object. There is nothing in the RESTful service definition that specifies the form of the JSON object. So the user must 'know' the form of the valid data that the server expects and also the form of the response. In the JThermodynamicsCloud ontology definition, the exact form of the JSON data needed to perform the task and the expected JSON response is specified. Thus the ontology provides documentation for the user of the service.However, since the ontology is machine-readable, its role of just documentation can be expanded. For example, though not implemented yet, the ontology could provide a level of input checking to see that the JSON object in the POST has all the necessary information. Also the machine readable ontology could be used to set up the user interface.
RESTful services in JThermodynamicsCloud are of two types:
Transactions: All modifications to the database are done using transactions. The ontology classes are subclasses of dataset:TransactionEvent which itself is a subclass of the Dublin Core dcmitype:Event.
Services: These are operations which query the database and/or the ontology. The ontology classes are subclasses of dataset:DatabaseServicesBase which itself is a subclass of PROV ontology prov:SoftwareAgent.
The input and output structure of the RESTful service call is the same. The input data is a JSON object, found in the body of the POST request. The body contains two elements:
Name: The name of the service, given by 'service' for a Service name and prov:activity for the Transaction name.
Data: For transactions the dataset:activityinfo property value is the JSON object with necessary information. These JSON objects are a subclass of dataset:ActivityInformationRecord (which is a subclass of dcat:CatalogRecord from the DCAT ontology). For services, the data is found directly in the body.
The response of the both services and transactions have the form as described by the dataset:ServiceResponseInformation:
dataset:ServiceProcessSuccessful (dataset:servicesuccessful): This is boolean which is true if the transaction or service was successful.
dataset:ServiceResponseMessage (dataset:serviceresponsemessage): This is a message (basically HTML or plain text) giving information about the success or failure about the process. The message is meant to be an output within the user interface.
dataset:SimpleCatalogObject (dataset:simpcatobj): This is an array of objects created by the transaction or the objects wanted by the service.
The purpose of transactions are to keep track of every change in the database. Whenever the database is to be modified, a RESTful transaction is performed. The purpose of a transaction is to have a trace the evolution of a database catalog object. To perform a transaction, the prerequisites to the transaction have had to be performed. These prerequisites are themselves transactions. In this way the user can trace the evolution of the database catalog object by tracing through the transactions that were used to create the current database object. To perform a transaction, first the prerequisites of the transaction must be collected. The transaction ontology definition contains the list of prerequisite transaction classes. The prerequisite for the process is a database transaction object of this class. When a transaction process is initiated, the set of database transaction catalog objects are retrieved. The transaction class can be used to find the specific transaction needed automatically, or, at least, limit the choices for the user. Each of these transaction objects (created previously by another transaction) has the FirebaseID's of the needed prerequisites. The FirestoreID's are used to retrieve from the database the actual prerequisite catalog objects. These catalog objects are then passed to the transaction process.
In order to perform the transaction, in addition to the list of prerequisite transaction catalog objects, some additional information may be needed to guide the process. These are specified through a dataset:ActivityInformationRecord (a subclass of dcat:CatalogRecord of the DCAT ontology) record object. The properties of this record object supplements the prerequisite data. In the ontology definition of the transaction, the specific class of dataset:ActivityInformationRecord gives a specification of the specific data needed. In the data sent to the RESTful service this information is under the dataset:activityinfo property.
The final output of a transaction process is an array of catalog objects of the same class. These are passed back through the RESTful process response. Each catalog object has the FirestoreID of the transaction that created it. The FirestoreID of each of the output catalog objects are listed in the database transaction object of the process.
The RESTful service differs from a transaction in that it only queries the database or the ontology and does no modifications. The definitions of the service in the ontology are subclasses of dataset:DatabaseServicesBase which itself is a subclass of prov:SoftwareAgent of the PROV ontology. The immediate subclass of dataset:DatabaseServicesBase have a one-to-one correspondence to the JAVA enumerations having the service process definitions in the RESTful implementation. The subclasses of these classes correspond to the names of the services.
The ontology definition for each service contains the data that is expected to perform that service. Simple entities, subclasses of dataset:Component, are the property of dcterms:hasPart and compound objects, subclasses of dataset:ChemConnectCompoundDataStructure (which is a subclass of dcat:CatalogRecord of the DCAT ontology), are properties of dcat:record. The property of ssn:hasOutput has the class of the output object. This is the object that makes up the array in the response under dataset:simpcatobj.