Distance Web Service

The Distance Web service is used to get the distance (measure of distance) between two UMBEL reference concepts by following the path of a transitive property.

Usage

This Web service is intended to be used by any user that wants to get the distance between two UMBEL reference concepts. No permissions are required to query this Web service endpoint. To access this endpoint, you simply have to send a HTTP GET query to the proper endpoint URL per the specifications below.
 
HTTP Method:
  • GET
Possible Accept: HTTP header field value:
  • */*: return the distance in JSON
  • application/json: return the distance in JSON
  • application/*: return the distance in JSON
  • application/xml: return the distance in XML
  • text/xml: return the distance in XML
  • text/plain: return the distance in plain text
URL:
  • http://umbel.org/ws/distance/uri-1/uri-2/property
Parameters:
  • uri-1: this parameter is the end URI of the starting UMBEL reference concept such as Person that refers to its full URI http://umbel.org/umbel/rc/Person.
  • uri-2: this parameter is the end URI of the ending UMBEL reference concept such as LegalAgent that refers to its full URI http://umbel.org/umbel/rc/LegalAgent.
  • property: this parameter is the transitive property to follow to find the distance between the two concepts. This parameter can be one of:
    • broader
    • narrower
    • sub-class-of
    • super-class-of

Serializations

The Get Concept endpoint currently supports three serialization formats:
  • JSON
  • XML
  • Plain text
 
The distance returned in JSON is a single object with a distance attribute and the actual distance as value.
 
    {"distance": "5"}
 
The distance returned in XML is a single distance element and the actual distance as value.
 
    <?xml version="1.0" encoding="utf-8" ?>
    <distance>3</distance>
 

Examples

Here are a series of examples that use cURL for querying the Get Distance Web service endpoint.
 
Get the distance between the umbel:Person and the umbel:LegalAgent reference concepts for the property broader in JSON:
  curl -H "Accept: application/json" "http://umbel.org/ws/distance/Person/LegalAgent/broader"
 
Get the distance between the umbel:Person and the umbel:LegalAgent reference concepts for the property broader in XML:
  curl -H "Accept: application/xml" "http://umbel.org/ws/distance/Person/LegalAgent/broader"
 

Errors

Here is the list of possible HTTP errors that can be returned by this endpoint:
 
HTTP Error Message Description
404
Unknown reference concept URI: Concept The URI of one of the reference concepts does not exist.
404
Unknown property requested. It should be one of: broader, narrower, sub-class-of or super-class-of The specified property is not existing or has a typo.
404
The concept [uri-1] is not connected to the concept [uri-2] for this property [property] The two specified concepts are unconnected by the specified property.
406
Unsuppoted mime requested The Accept: HTTP headers doesn't contain any supported mime types. If this happens, make sure that you are requesting a supported mime type.
500
empty An internal UMBEL Web service error occurred. If this happens, please contact us with the query that caused the error.
 

Copyright © 2008-2017. Structured Dynamics LLC. All content available via Creative Commons Attribution 3.0