|
||||
|
Hosted
by
|
|
|||
| Web Services |
API PhilosophyMultiple kinds of results can be generated by the Structured Dynamics UMBEL Web services. Each request to an individual Web service returns a document of resultsets, or an HTTP status (error) code if the request is malformed or an error occurred. Each results document can be serialized in many ways, and may be expressed as either RDF or pure XML. Linked Data BasisThe primary data model used to describe the results of each Web service is RDF (Resource Description Framework). The RDF graph data model is a powerful one. When combined with proper vocabularies, the RDF data model is a flexible and precise way to express these results. The Structured Dynamics UMBEL Web services may be serialized as RDF+XML, RDF+N3, or, in some cases, RDFa. However, not all data consumers may have the tools or internal capabilities to process the RDF data model or its serializations. There are also use cases where XML is the preferred means for communicating results. To accommodate this spectrum, the Structured Dynamics UMBEL Web services may also be provided as pure XML with a DTD (Document Type Definition ) (eventually to be more formally described as an XML Schema). Thus, consumers of these Web services have maximum flexibility and choice: Results can be processed directly as either XML or RDF in a variety of serializations. This also opens up the processing of results with a broader range of XML and RDF tools such as parsers, validators and datastores for a wider range of applications and environments. Thus, consumers of these Web services have maximum flexibility and choice: Results can be processed directly as either XML or RDF in a variety of serializations. This also opens up the processing of results with a broader range of XML and RDF tools such as parsers, validators and datastores for a wider range of applications and environments. Design PhilosophyA number of considerations govern Structured Dynamics's design of these UMBEL Web services. Flexible ConsumptionIn keeping with current Web diversity, the design provides multiple serializations and both RDF and XML result forms. Each Web service is also characterized by multiple options and parameters so as to tailor final results. Pipeline Model and Internal Canonical FormThe general architecture is geared to support either a pipeline design model or atomic and compound Web services. The canonical data format for possible data transfer between Web services is the standard XML result form. This design enforces modularity and promotes re-use. RESTful ArchitectureAll Web services are fully RESTful (Representational State Transfer). In addition to current RESTful practices, the Structured Dynamics UMBEL Web services also use HTTP status codes for all error messages and accept and enforce charset, encoding, language and serialization options via the Accept request-header field. Terminology ConsistencyAll Web services are named as nouns or compound nouns and all parameter and option calls are consistent with RDF practice and terminology. This design is consistent with best practices in a Web-oriented architecture (WOA) that is conformant with REST and linked data based on RDF. Baseline and Advanced ServicesThe design is geared to support both free, baseline Web services as provided for the UMBEL project and advanced options and utilities as may optionally be offered. All baseline services offered as Structured Dynamics UMBEL Web services are provided under the Creative Commons 3.0 Share Alike with Attribution license. Structured Dynamics reserves the right to limit access to the baseline UMBEL service based on demand. Two Forms of Web ServiceTwo kinds of Web services exist: (1) atomic Web services and (2) compound Web services. A compound Web service is composed of multiple atomic Web services interacting together. Each atomic Web service performs one function given some parameters. The result of any Web service is a resultset that describes the result of the computation of the Web service. The main goals of the XML data structure used by the Web services are:
Each Web service has its own API documentation page, which when combined with its related DTD, provides a full specification for the XML data returned by that Web service. The Web Service Endpoint RequestThe way to communicate with any Web service is by using the HTTP protocol. Any Web service endpoint can be accessed via its URL, which may combine an overall service name (e.g., 'finder') with its specific implementation or focus (e.g., 'named_entity') . A URL example is: http://umbel.structureddynamics.com/ws/finder/named_entity/ The standard text reference to this example Web service then becomes: Finder Named Entity Web Service There are two methods that can be used to communicate with a Web service endpoint: GET or POST. The method to use differs from one service to another. This method is specified in the API documentation of each Web service. Below is a description of the HTTP header that a data consumer should use to request a resultset to any Web service. GET MethodHTTP header sent by the data consumer: GET /ws/finder/named_entity/?mode=pref_label&text=madonna HTTP/1.1 The HTTP header sent by back by the Web service endpoint: HTTP/1.1 200 OK Additionally the data consumer can specify different charsets, language and encoding in its request. However only the "utf-8" charset, the "en" language and the "identity" encoding are supported by the baseline UMBEL Web services endpoints. POST MethodHTTP header sent by the data consumer: POST /ws/extractor/subject_concept/ HTTP/1.1 The HTTP header sent by back by the Web service endpoint: HTTP/1.1 200 OK Additionally the data consumer can specify different charsets, language and encoding in its request. However only the "utf-8" charset, the "en" language and the "identity" encoding are supported by the baseline UMBEL Web services endpoints. Note that the parameters to pass to the Web service endpoint are added in the body of the query. For a complete description of HTTP/1.1 header fields, please consult the RFC 2616 document. The Data StructureHere is a brief description of the major elements that comprise the XML data structure. The API and DTD documentation for each Web service provides sample results fragments that help illustrate this structure. <resultset />The goal of any Web service is to return results. The root element of any Structured Dynamics UMBEL Web service is the
<subject />Any query to a Web service refers to a "subject" (consistent with the understanding of subject within the standard subject-predicate-object RDF triple). This subject can be a resource referred to by its ID, it can be one or multiple keywords of a search string, it can be text of one thousand words to be analyzed, or other options. A resultset is composed of one or multiple subject(s) depending on the Web service. This means that the subject element represents the subject of a query to a Web service endpoint. A subject has a type and a URI. The type of a subject can be seen as its kind. The URI of a subject is its unique identifier. <predicate />Any Web service takes the subject of a query and processes it according to the procedures set by other input parameters to the query. The result of this processing is to relate a subject to other things (objects; see below) using different predicates. Any subject has zero, one or multiple predicate(s) relationships with other objects. Every predicate has a type. The type of a predicate can be seen as the kind of relationship between two things (a subject and an object). <object />Any predicate refers to one or multiple objects. An object is a thing such as a subject with a type and an optional URI. An object could be the subject of another query. Subject and object are the same in that both refer to a "thing" (or collections of things, in which case they are a class). The only difference between the two elements is the way in which they are referenced by a predicate, as either a subject or an object. An object has a type and a URI. The type of an object can be seen as its kind. The URI of an object is its unique identifier. It is optional if the object reference is a literal, such as a string name or a number. A special kind of object exists: rdfs:Literal. The characteristics of this kind of object will be discussed in a special section below. <reify />Sometimes it is useful to be able to assert facts about a given triple statement <subject, predicate, object>. The example below means: we have a subject that is a bibo:Document. This document has a predicate relationship umbel:isAbout with the thing, that itself is a umbel:SubjectConcept, referred as http://.../War. Basically, this triple relationship means: "I have a document that is about War". However I would also like to assert a certain ratio that shows the confidence level in asserting that statement. By using the umbel:withLikelihood reification property, we can assign a confidence level regarding the "fact" (assertion) of the initial triple statement, as follows: <<bibo:Document, umbel:isAbout, umbel:SubjectConcept>, umbel:withLikelihood, "0. 87345872835434">. This reification gets expressed in the XML data structure as:
<resultset> <subject type="bibo:Document" uri="http://..."> <predicate type="umbel:isAbout"> <object type="umbel:SubjectConcept" So, basically, the reify element helps us to assert a fact about another fact (triple statement). Data consumers should thus parse the XML document in this following way: If there is a <reify /> element within the body of a <object /> element, the data consumer must check the three parent nodes of the <reify /> element to compose the assertion fact about <subject, predicate, object> comprising the three nodes of the triple. Unique Identifiers: URIsNearly all resources — subject, predicate or object — has a unique identifier called a URI. (Subjects and predicates must have a URI; objects most frequently do, but sometimes may optionally be assigned a literal.) These URIs are unique to each resource. Since these IDs are unique, if a Web service A refers to a resource X and another Web service B also refers to a resource X, then both Web services A and B refers to the same thing. This understanding must hold true for the reason that atomic Web services can easily interact together to create compound Web services. However, sometimes, the subjects or the objects of a resultset may not have a defined URI (the attribute). If such a case happens, the consumer of this Web service data must itself define a unique identifier for that thing. LiteralsA literal is a special kind of object. Unlike any other object, a literal object can not be a subject of a predicate. (Technically, a resource could describe a literal, but the literal itself can't be described; but this fact is out of the scope of this document). An example of a resource that describes a literal is the bibo:Document use case described above. A literal object may not also have a URI attribute. Flexibility of this XML Data StructureThis XML data structure is thus flexible enough to describe any relation within an RDF graph produced by any Structured Dynamics UMBEL Web service. The advantage of re-using the triple assertions of the RDF data model with types and URIs is that a data consumer can easily handle the data produced by any Web service, even without knowing the type of the subjects, predicates and objects returned by that Web service. The data consumer can always say: I have this thing that refers to this other thing with this given predicate. The data consumer can manipulate results in some ways even if it doesn't know much or anything about the types of those things. This consistent abstraction is helpful since even if the Web services evolve and change over time, the data consumers of these Web services will be able to handle the things it knows, and only discard the new types that have been added that it may not know, all without having to change anything in the procedures that manage the resultsets returned by these Web services. DTDsEach Web service has its own DTD. These DTDs have been created to help data consumers validate the outputs of these Web services. It is also useful to let data consumers know what they should expect from a given Web service. The full listing of the DTD for an existing Web service is linked to on its Web service API documentation page. HTTP Status Codes (Error Messages)Besides standard information, the Structured Dynamics UMBEL Web services also communicate HTTP status codes in cases of a malformed request or error. The status codes applicable to each Web service are specified in their applicable APIs, but in general include:
|