The CB-NL API

Introduction to the XML API

The CB-NL core and some context ontologies are accessible by a SparQL (RDF/OWL) API. This API is available at http://api.cbnl.org/sparql. This API is decribed here: SPARQL-endpoint. This REST API accepts SPARQL queries, and returns RDF results (as Json or XML, as requested).

The team recognizes that many software vendors do not have the knowledge or inclination to use the RDF/OWL API, create SPARQL queries and process the results. Therefore an alternative API is provided, accepting commands and parameters rather than full queries, and returning expressive XML, rather than SPARQL results. This API is loosely based on the BsDD API 1.0 syntax. This is described below. 

The results of the XML API calls (the “Payload”) conform to an XML Schema. A separate XML schema is created for each type of result. All schemas are based on a common information model, expressed in UML. This UML model shows what constructs are recognized as part of the OWL ontology, what (meta)data these constructs have, and what relations exist. The model is documented in this “base UML”.

For each payload a separate, derived UML is created, and a corresponding XML schema is provided. The API is modelled as:

• PayloadServices-items — Return all concepts, relations, collections (…) within a single context and release. Only records the identifying data of the item.
• PayloadServices-construct — Return all information on concept, relation or collection within a single context and release. This includes all meta information, and URI of supertypes, relations and collections.
• PayloadServices-definition — Return a concise definition of a concept.
• PayloadServices-links — Provide all "links" that any item has with other items. This concerns collections, relations, concepts, data properties, contexts, libraries and works.
• PayloadServices-search — Search for items within a single context and release, based on a text search. This returns all fragments including a marker for the location of the text found and a reference to the item. The item is identified by URI, name and status info. 
• PayloadServices-comments — Return all comments on a single item in a single context but any release. This includes all comment info, including the release.
• PayloadServices-library — Return information on the library specified.

The Payload UML is designed specifically for the CB-NL. Mostly the same information may be represented by payloads that follow IFC 1.0 (the payload model for BsDD calls). Therefore, an alternative Payload model (and schema) is available to represent the ontology in that form. This is work in progress.

Check the following resources for more detailed information.

• SPARQL API (http://api.cbnl.org/sparql
• XML API overview (http://api.cbnl.org/xml/1.0) 
• UML base model (below)
• IFD schema (http://bsddpilot.catenda.no/docs/objects.xsd, http://bsddpilot.catenda.no/docs/pset.xsd )
• BsDD API (Peregrine API) (http://bsddpilot.catenda.no/docs/
• Overview of the BsDD API (http://staging.bsdd.buildingsmart.org/docs/index.html
• REST (Representational State Transfer (REST))

The BsDD API format

The BsDD (http://www.buildingsmart.org/standards/ifd) offers an API for quering and updating the constructs in the data dictionary. To this end it defines a REST syntax. Requests specified using this syntax will return some result (which may include an update in the dictionary itself). This result takes the form of an XML or JSON message. The format of the result is according to a schema with namespace http://peregrine.catenda.no/objects. This schema is generic, and all elements are optional; they will be inserted into the result when needed.

CB-NL has decided that the syntax of the API is attractive and should be the starting point for the CB-NL XML API. So access to CB-NL takes the form of similar requests.

The BsDD API is based on passing GUIDs, as the objects are identified by GUIDs. Example:
http://staging.bsdd.buildingsmart.org/docs/api/4.0/IfdConcept/19ed4236-4a47-4497-9c15-96cc4b74f089 

For the CB-NL, this strategy cannot be adopted, as URIs can only be passed in URLs as request parameters. Therefore, we use two related approaches.

The special term “uri” is used to denote the URI passed as a request parameter, as in:
http://api.cbnl.org/xml/1.0/core-cbnl/20140901/Item/uri?uri=http%3A%2F%2Font.cbnl.org%2Fcb%2Fdef%2FBrug  

We use the term “Item” to specify that any type of Item is allowed, although the URI (http://ont.cbnl.org/cb/def/Brug) represents a concept.

For concepts that are in the CB-NL core model the URI parameter syntax is equivalent to:
http://api.cbnl.org/xml/1.0/core-cbnl/20150501/Concept/Brug 

which is translated automatically to the URI http://ont.cbnl.org/cb/def/Brug (resolved in the latest release).

For relations that are in the CB-NL core model this is equivalent to:
http://api.cbnl.org/xml/1.0/core-cbnl/20150501/Relation/DoelFunctie 

For collections that are in the CB-NL core model this is equivalent to:
http://api.cbnl.org/xml/1.0/core-cbnl/20150501/Collection/Draagconstructies 

The URI strategy states that the URI  itself should provide access to information. Which type of information this is, is determined by content negotiation. 

The CB-NL URI strategy uses the following conventions for any URI passed 

• When accessed by internet browser (accept-encoding=html)  rewrites to an HTML information page which shows in which context(s) and release(s) the item occurs. 
• When accessed by REST (accept-encoding=xml) it returns an XML payload which represents in which context(s) and release(s) the item occurs.

Introduction to the Payload model

This section describes the base model of all payload data. 

The base model is composed in accordance with a “set of rules”, a metamodel, developed by Kadaster in collaboration with the Dutch Chamber of Commerce, Waarderingskamer, and VNG/KING. This metamodel is published elsewhere. 

The base model is the foundation of all individual payload models. These models are also in accordance with this metamodel, and offer a view on the base model. The basic approach is:

1. The base model shows all we’ve got.
2. The payload model shows what’s needed in a particular response.
3. To understand any payload model requires understanding of the base model. 

The base model is as follows.

A particular payload model consists of two parts:

• A “Header” block that specifies which objects are relevant in the response.
• A selection of the base model that only identifies the objects and properties that are passed.

As an example, the following UML model shows which parts are relevant for the “library” information call (PayloadServices-library):

The subset of the base model relevant for this service response is modelled separately, offering a view on the base model:

The Payload JSON format

The information passed in XML is also available as JSON. In order to access REST services in JSON format, pass the parameter mode=json, for example:

http://viewer.cbnl.org/bsdd-api/v1.0/core-cbnl/20150501/Concept/uri?uri=http%3A%2F%2Font.cbnl.org%2Fcb%2Fdef%2FBrug&mode=json

The JSON result is an immediate translation of the XML structure (and UML model) to JSON constructs. 

The Payload XML format

This section describes the structure of the XML documents returned in an XML API call.

The UML specification is complete, and identifies all information passed back in an API response. This response is primarily formatted as an XML message. There is a fixed set of rules that is followed to transform a UML class, attribute, association and so on, to generate a corresponding XML message. These rules are as follows.

1. Classes are modelled as global elements
2. Attributes and relations are modelled as local elements
3. When an association’s target is an Object type (stereotype <<objecttype>>), the target is represented by a Ref element. This Ref element holds a reference (xlink href) to the URI of the targeted item. The targeted item is then part of a special “collection” element, called <ResultComponents>. In fact, all items are placed in this collection, this allowing full networked structures to be passed in response, as well as a structurally validating XML schema.

The XML API overview (http://api.cbnl.org/xml/1.0) is generated based on available services, and may change in time. It holds the following information.

Model name — XSD | APP | ZIP 

• XSD shows the XSD in pretty-printed form
• APP provides access to all (technical/managerial) information that concerns the model and the XML Schema build
• ZIP holds the complete APP as a download ZIP.

The APP shows the readme file, which gives access to documentation, the UML model, and the XSD.

The overview provides examples of API calls that conform to the API syntax and the response format as described. 

Note: for technical purposes a non-cached version of each call may be accessed using the [nc] link.