OSF Web Services

From OSF Wiki
Jump to navigation Jump to search

OSF Web Service is a platform-independent Web services framework for accessing and exposing structured RDF (Resource Description Framework) data. Its central organizing perspective is that of the dataset. These datasets contain instance records, with the structural relationships amongst the data and their attributes and concepts defined via ontologies (schema with accompanying vocabularies).

The OSF Web Service middleware framework is generally RESTful in design and is based on HTTP and Web protocols and open standards. The initial OSF Web Service framework comes packaged with a baseline set of 27 Web services in CRUD, revisioning, search, tagging, ontology management, and export and import. All Web services are exposed via APIs and SPARQL endpoints. Each request to an individual Web service returns an HTTP status and optionally a document of resultsets. Each results document can be serialized in many ways, and may be expressed as either RDF, pure XML, JSON, or different flavors of irON.

In initial release, OSF Web Service has direct interfaces to the Virtuoso RDF triple store (via ODBC, and later HTTP) and the Solr faceted, full-text search engine(via HTTP), the OWLAPI and the Gate NLP framework. However, OSF Web Service has been designed to be fully platform-independent. Support for additional datastores and engines are planned. The design also allows other specialized systems to be included, such as analysis or advanced inference engines.

The framework is open source (Apache 2 license) and designed for extensibility. OSF Web Service and its extensions and enhancements are distributed and documented on the OSF Web site.

Linked Data Basis

The 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 OSF Web Services may be serialized as RDF+XML and RDF+N3 and few others (see the web service endpoints' documentation page for the complete list, per endpoint). New serializations can be added easily.

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 OSF Web Services endpoints may be able to serialize the resultset using a wide array of different serialization format. Also, a series of converter web service endpoint can be used to convert resultsets returned by these endpoints.

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 Philosophy

A number of considerations govern the design of these OSF Web Services.

Flexible Consumption

In 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 Form

The 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 Architecture

All Web services are generally RESTful (Representational State Transfer). In addition to current RESTful practices, the OSF 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 Consistency

All 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 conforms with REST and linked data based on RDF.

Two Forms of Web Service

Two 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:

  • To have consistent names with the RDF data model and its vocabularies
  • To be flexible enough to be able to describe the same relationships between things that are described in RDF
  • To be easy to manipulate using existing XML parsing tools, libraries and XML data consumers.

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.

HTTP Status Codes (Error Messages)

Besides standard information, the OSF 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.

Both Management and User Services

There are two general kinds of Web services that belong to OSF Web Services:

  1. WSF management Web services
  2. User-oriented Web services

The Web services oriented toward the management of OSF Web Service (#1) are the ones supervising the overall work of the WSF. They authorize queries to the endpoints, they register new Web services endpoints within the network, they manage access permissions, etc.

The Web services oriented toward the users of OSF Web Service (#2) are all the other Web services that general users can use to archive, manipulate and play with structured data hosted on the WSF.

Here is a listing of the current OSF Web Services and to which of these categories they belong:

WSF management Web services User-oriented Web services