List of UMBEL Web Services    Invoke this Web Service    Short Description of this Web Service    Access this Web Service
 
API and Documentation

Finder: Subject Concept Web Service API Documentation






For background, we suggest first reading the about section for this Web Service. Also, you may want to consult this document for an overall discussion of API design and philosophy.

Developers communicate with the Finder: Subject Concept Structured Dynamics LLC. UMBEL Web service using the HTTP GET method. You may request one of the following mime types: (1) text/xml, (2) application/rdf+xml and (3) application/rdf+n3. The content returned by the Web service will be serialized using the mime type requested and the data returned will depend on the parameters selected.

Web Service Endpoint Information

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline UMBEL Web services may not offer other values than the default.

HTTP Method:
  • GET

Possible "Accept:" HTTP header field value:
URI:
  • http://umbel.structureddynamics.com/ws/finder/subject_concept/
    ?mode=param1&text=param2&lang=param3


URI dynamic parameters description:

Note: All parameters have to be URL-encoded
  • param1. One of:
    • " all_labels (default)": Search within all labels
    • " uri_label": Search for the subject concept URI only
    • " pref_label": Search for the preferred label only
    • " alt_label": Search for the alternative label(s) only
  • param2. The search string
  • param3. One of:
    • " en (default)": Labels of resultsets in English if available

Example of Returned XML Document

This is an example of the XML document returned by this Web service endpoint for a given URI. This example returns a list of UMBEL subject concepts where one of their preferred label match the example "project" search string.


Query:
  • http://umbel.structureddynamics.com/ws/finder/subject_concept/
    ?mode=pref_label&text=project
"Accept:" HTTP header field value::
  • text/xml

Result:
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!DOCTYPE resultset PUBLIC "-//Structured Dynamics LLC.//
    Finder: Subject Concept DTD 0.1//EN"
    "http://umbel.structureddynamics.com/ws/dtd/finder/subject_concept.dtd">
  3. <resultset>
  4.   <subject type="rdf:Bag" uri="">
  5.     <predicate type="rdf:li">
  6.       <object type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/ConstructionProject"/>
  7.     </predicate>
  8.     <predicate type="rdf:li">
  9.       <object type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/Project"/>
  10.     </predicate>
  11.     <predicate type="rdf:li">
  12.       <object type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/ProjectManager"/>
  13.     </predicate>
  14.     <predicate type="rdf:li">
  15.       <object type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/ProjectReport_CW"/>
  16.     </predicate>
  17.     <predicate type="rdf:li">
  18.       <object type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/ResearchProject"/>
  19.     </predicate>
  20.   </subject>
  21. </resultset>

DTD of the XML Document

  1. <!DOCTYPE resultset [
  2.  
  3.         <!ELEMENT resultset (subject)+ >
  4.        
  5.         <!ELEMENT subject (predicate)*>
  6.         <!ATTLIST subject type (rdf:Bag) "rdf:Bag">
  7.         <!ATTLIST subject uri CDATA #IMPLIED>
  8.  
  9.         <!ELEMENT predicate (object)>
  10.         <!ATTLIST predicate type (rdf:li) "rdf:li">
  11.  
  12.         <!ELEMENT object EMPTY>
  13.         <!ATTLIST object type (umbel:SubjectConcept)
    "umbel:SubjectConcept">
  14.         <!ATTLIST object uri CDATA #REQUIRED>
  15.  
  16. ]>

Descriptions of the Types of XML Elements

Here are descriptions of the types of XML elements that might be returned from from this Web service. Please read the XML data structure documentation to understand how the data is structured within these XML documents.

  • rdf:Bag (subject/object). An unordered set of resources returned by the
    Web service
  • umbel:SubjectConcept (subject/object). An UMBEL subject concept resource
    returned by the Web service for the requested parameters
  • rdf:li (predicate). An item of a rdf:Bag that refers to a resource

Example of Returned RDF/XML Document

Here is an example of a RDF/XML document returned by this Web service endpoint for a given URI. This example returns a list of UMBEL subject concepts where the preferred label matches the example "project" search string.


Query:
  • http://umbel.structureddynamics.com/ws/finder/subject_concept/
    ?mode=pref_label&text=project
"Accept:" HTTP header field value:
  • application/rdf+xml

Result:
  1. <?xml version="1.0"?>
  2. <rdf:RDF xmlns:umbel="http://umbel.org/umbel#"
    xmlns:owl="http://www.w3.org/2002/07/owl#"
    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  3.  
  4. <rdf:Bag>
  5.     <rdf:li rdf:resource="http://umbel.org/umbel/sc/ConstructionProject" />
  6.     <rdf:li rdf:resource="http://umbel.org/umbel/sc/Project" />
  7.     <rdf:li rdf:resource="http://umbel.org/umbel/sc/ProjectManager" />
  8.     <rdf:li rdf:resource="http://umbel.org/umbel/sc/ProjectReport_CW" />
  9.     <rdf:li rdf:resource="http://umbel.org/umbel/sc/ResearchProject" />
  10. </rdf:Bag>
  11.  
  12. </rdf:RDF>

Example of Returned RDF/N3 Document

Here is an example of a RDF/N3 document returned by this Web service endpoint for a given URI. This example returns a list of UMBEL subject concepts where the preferred label matches the example "project" search string.


Query:
  • http://umbel.structureddynamics.com/ws/finder/subject_concept/
    ?mode=pref_label&text=project
"Accept:" HTTP header field value:
  • application/rdf+n3

Result:
  1. @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
  2. @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
  3. @prefix owl: <http://www.w3.org/2002/07/owl#> .
  4. @prefix umbel: <http://umbel.org/umbel#> .
  5. _:bnode0 rdf:type rdf:Bag ;
  6.     rdf:li <http://umbel.org/umbel/sc/ConstructionProject> ;
  7.     rdf:li <http://umbel.org/umbel/sc/Project> ;
  8.     rdf:li <http://umbel.org/umbel/sc/ProjectManager> ;
  9.     rdf:li <http://umbel.org/umbel/sc/ProjectReport_CW> ;
  10.     rdf:li <http://umbel.org/umbel/sc/ResearchProject> .

HTTP Status Codes

Here are the possible HTTP status (error) codes returned by this Web service endpoint.

  • Code: 200
    • Message: OK
  • Code: 400
    • Message: Bad Request
    • Message description: No search keywords
  • Code: 406
    • Message: Not Acceptable
    • Message description: Unacceptable mime type requested
  • Code: 500
    • Message: Internal Error