CTS2-LE REST API: Read Maps and Map Versions

Aus CTS2-LE
Zur Navigation springen Zur Suche springen

A general note on maps and map versions: The underlying implementation of the CTS2 information model identifies a map by its uri only. A specific version of a map will then have its own name (resourceID wrt. the information model) and a versionId. A map version can be uniquely identified by the pair of versionOf and versionId. Since the resourceID is a system intern identifier, using it as a path parameter to identify a map version is not suitable. Because of that any call that a.) tries to reference a map by its name rather than by its uri (versionOf) or b.) tries to reference a map version without specifying the version id and the uri will result in an exception.
Response format and language may be controlled either by a Query Parameter: ?referencelanguage={language} or ?format={format} OR by the HTTP 'Accept' and 'Accept-Language' Header Parameters. Query OR Header parameters will both the accepted as valid, however, the Query parameters will ALWAYS take precedence over the Header parameters, if both are present. Currently, we only support application/xml as format. The language attribute will be ignored.

Root-URL: /WebCts2LE/rest/

Retrieve all maps

  • MapCatalogQueryService:resolve: Resolve a MapCatalogDirectoryURI as a set of MapCatalogSummaryEntries. This service does not support the QueryService and thus, no query parameters (except referencelanguage and format) will be processed.
  • Path: /maps
  • Method: GET
  • Path Parameters: -
  • Query Parameters:
page the 0-based page number used for paging result sets. Default is 0.
maxtoreturn the maximum number of entries that may be present in a return Directory. If maxToReturn is not supplied, a block size of 100 is used.
  • returns: map:MapCatalogEntryList

Example Response Structure for call /maps

<?xml version="1.0" encoding="UTF-8"?>
<MapCatalogEntryList xmlns="http://www.omg.org/spec/CTS2/1.1/MapCatalog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" complete="COMPLETE" numEntries="1">
   <core:heading xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>maps</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>application/xml</core:val>
       </core:parameter>
       <core:parameter arg="Accept-Language">
           <core:val>de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4</core:val>
       </core:parameter>
       <core:parameter arg="page">
           <core:val>0</core:val>
       </core:parameter>
       <core:parameter arg="maxtoreturn">
           <core:val>100</core:val>
       </core:parameter>
       <core:accessDate>2016-07-14T14:02:41</core:accessDate>
   </core:heading>
   <entry xmlns="http://www.omg.org/spec/CTS2/1.1/MapCatalog">
       <entry mapName="UNKNOWN" about="example:mapping">
           <fromCodeSystem uri="example:terminology">ExampleCS2013</fromCodeSystem>
           <toCodeSystem uri="example:anotherTerminology">ExampleCS2016</toCodeSystem>
           <versions>http://localhost:8080/WebCts2LE/rest/map/_/mapversions?mapuri=example:mapping</versions>
           <currentVersion>
               <core:mapVersion xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">ExampleMappingVersion2</core:mapVersion>
           </currentVersion>
       </entry>
   </entry>
</MapCatalogEntryList>

Retrieve a map by uri

  • Retrieve a MapCatalogEntry by URI. Accessing a Resource By a 'URI'
    • A CTS2 Resource may also be accessed by its URI or "AlternateID." This convention varies slightly from the 'by name' convention in that the URI is not specified in the URL path, but as a query parameter. This is done to eliminate the need for complex encoding that would be necessary to embed a URI into a URL path. The convention for accessing a resource by its URI is
    /{resourceType}byuri?uri={uri|alternateId}
  • Path: /mapbyuri
  • Method: GET
  • Path Parameters: -
  • Query Parameters:
uri the URI, OID or alternateID of the requested resource
  • returns: redirect to /map/_?mapuri=uri; e.g. the call /mapbyuri?uri=example:mapping redirects to /map/_?mapuri=example:mapping

Exceptions

  • UnknownMap if there is no map with the given uri

Retrieve a map by name

  • MapCatalogReadService:read: Retrieve a MapCatalogEntry by name or URI.
    Please note that this service implementation does not support to request a map by its name. The client has to specify a query parameter and replace the path parameter by an underscore '_'. e.g. "/map/_?mapuri=http://www.somemapping.de".
  • Path: /map/{mapid}
  • Method: GET
  • Path Parameters:
mapid the Name of the Map - this parameter will be ignored; it should always be set to '_'
  • Query Parameters:
mapuri the URI, OID or alternateID of the requested resource
  • returns: map:MapCatalogEntryMsg without the following elements and attributes: currentVersion, versions, href-attributes in from and to elements

Example Response Structure for call /map/_?mapuri=example:mapping

<?xml version="1.0" encoding="UTF-8"?>
<MapCatalogEntryMsg xmlns="http://www.omg.org/spec/CTS2/1.1/MapCatalog" xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <core:heading xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>map/_</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>application/xml</core:val>
       </core:parameter>
       <core:parameter arg="Accept-Language">
           <core:val>de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4</core:val>
       </core:parameter>
       <core:parameter arg="mapuri">
           <core:val>example:mapping</core:val>
       </core:parameter>
       <core:accessDate>2016-07-14T14:30:23</core:accessDate>
   </core:heading>
   <map xmlns="http://www.omg.org/spec/CTS2/1.1/MapCatalog" mapName="UNKNOWN" about="example:mapping">
       <fromCodeSystem uri="example:terminology">ExampleCS2013</fromCodeSystem>
       <toCodeSystem uri="example:anotherTerminology">ExampleCS2016</toCodeSystem>
       <versions>http://localhost:8080/WebCts2LE/rest/map/_/mapversions?mapuri=example:mapping</versions>
       <currentVersion>
           <core:mapVersion xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">ExampleMappingVersion2</core:mapVersion>
       </currentVersion>
   </map>
</MapCatalogEntryMsg>

Exceptions

  • UnknownMap if
    • the name of the map (path parameter mapid) is not set to an underscore
    • the query parameter mapuri is not specified or is not an uri
    • there is no map with the given uri


Retrieve map versions for a specific map

  • MapVersionQueryService:resolve: Resolve a MapVersionDirectoryURI returning a directory of the map versions that it references. The path parameter is used to identify the mapping by its name. Please note that this service implementation does not support to request a map by its name. The client has to specify a query parameter and replace the path parameter by an underscore '_'. e.g. "/map/_/mapversions?mapuri=http://www.examplemapping.de".
  • Path: /map/{mapid}/mapversions
  • Method: GET
  • Path Parameters:
mapid the Name of the Map - this parameter will be ignored; it should always be set to '_'
  • Query Parameters:
mapuri the URI, OID or alternateID of the requested resource
page the 0-based page number used for paging result sets. Default is 0.
maxtoreturn the maximum number of entries that may be present in a return Directory. If maxToReturn is not supplied, a block size of 100 is used.
  • returns: mapVersion:MapVersionList

Example Response Structure for call /map/_/mapversions?mapuri=example:mapping

<?xml version="1.0" encoding="UTF-8"?>
<MapVersionList xmlns="http://www.omg.org/spec/CTS2/1.1/MapVersion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" complete="COMPLETE" numEntries="2">
   <core:heading xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>map/_/mapversions</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>application/xml</core:val>
       </core:parameter>
       <core:parameter arg="Accept-Language">
           <core:val>de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4</core:val>
       </core:parameter>
       <core:parameter arg="mapuri">
           <core:val>example:mapping</core:val>
       </core:parameter>
       <core:parameter arg="page">
           <core:val>0</core:val>
       </core:parameter>
       <core:parameter arg="maxtoreturn">
           <core:val>100</core:val>
       </core:parameter>
       <core:accessDate>2016-07-18T12:25:36</core:accessDate>
   </core:heading>
   <entry href="http://localhost:8080/WebCts2LE/rest/map/_/mapversion/1.0?mapuri=example:mapping">
       <entry xmlns="http://www.omg.org/spec/CTS2/1.1/MapVersion" mapVersionName="ExampleMappingVersion1" about="UNKNOWN">
           <versionOf uri="example:mapping">UNKNOWN</versionOf>
           <fromCodeSystemVersion>
               <core:version xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">1.0</core:version>
               <core:codeSystem xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" uri="example:terminology">ExampleCS2013</core:codeSystem>
           </fromCodeSystemVersion>
           <toCodeSystemVersion>
               <core:version xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">1.0</core:version>
               <core:codeSystem xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" uri="example:anotherTerminology">ExampleCS2016</core:codeSystem>
           </toCodeSystemVersion>
           <versionTag>1.0</versionTag>
           <entries>http://localhost:8080/WebCts2LE/rest/map/_/mapversion/1.0/entries?mapuri=example:mapping</entries>
       </entry>
   </entry>
   <entry href="http://localhost:8080/WebCts2LE/rest/map/_/mapversion/2.0?mapuri=example:mapping">
       <entry xmlns="http://www.omg.org/spec/CTS2/1.1/MapVersion" mapVersionName="ExampleMappingVersion2" about="UNKNOWN">
           <versionOf uri="example:mapping">UNKNOWN</versionOf>
           <fromCodeSystemVersion>
               <core:version xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">1.0</core:version>
               <core:codeSystem xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" uri="example:terminology">ExampleCS2013</core:codeSystem>
           </fromCodeSystemVersion>
           <toCodeSystemVersion>
               <core:version xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">1.0</core:version>
               <core:codeSystem xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" uri="example:anotherTerminology">ExampleCS2016</core:codeSystem>
           </toCodeSystemVersion>
           <versionTag>2.0</versionTag>
           <entries>http://localhost:8080/WebCts2LE/rest/map/_/mapversion/2.0/entries?mapuri=example:mapping</entries>
       </entry>
   </entry>
</MapVersionList>

Exceptions

  • UnknownMap if
    • the name of the map (path parameter mapid) is not set to an underscore
    • the query parameter mapuri is not specified or is not an uri

Retrieve a specific map version

  • MapVersionReadService:read: retrieve a specific version of a map by name or URI. This service implementation supports this call in the following manners: a.) A map version can be identified by means of its mapuri and version id. e.g. If a client requests the 2014 version of the mapping with uri "http://www.examplemapping.de", then he or she sends the following request: "/map/_/mapversion/2014?mapuri=http://www.examplemapping.de". The default version of a map can be requested by replacing both path parameters (mapid and mapversionid) by an underscore '_' and a '_def' respectively. b.) A map version can be identified by its unique id (resourceID). The first path parameter mapid should be replaced by an underscore '_'. The second path parameter mapversionid refers to the resourceID. The query parameter mapuri should be omitted.
  • Path: /map/{mapid}/mapversion/{mapversionid}
  • Method: GET
  • Path Parameters:
mapid the Name of the Map - this parameter will be ignored; it should always be set to '_'
mapversionid if the query parameter mapuri is given, the value of this parameter defines the version ID (set to '_def' to request the default version); if the query parameter mapuri is NOT given, the value of this parameter refers to the unique resourceID of the map version
  • Query Parameters:
mapuri the URI, OID or alternateID of the mapping, e.g. www.examplemapping.de; use this query parameter in conjunction with the path parameter mapversionid when the latter refers to the versionID of the requested value set definition
page the 0-based page number used for paging result sets. Default is 0.
maxtoreturn the maximum number of entries that may be present in a return Directory. If maxToReturn is not supplied, a block size of 100 is used.
  • returns: mapVersion:MapVersionMsg

Example Response

API Paths

  • a.) fetch by uri and version id: /map/_/mapversion/2.0?mapuri=example:mapping
  • b.) fetch by resourceID: /map/_/mapversion/ExampleMappingVersion2

The responses of a and b only differ in terms of their <core:heading> and <entries>-elements. Find below the response when requesting with path b. 

<?xml version="1.0" encoding="UTF-8"?>
<MapVersionMsg xmlns="http://schema.omg.org/spec/CTS2/1.0/MapVersion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <core:heading xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>map/_/mapversion/ExampleMappingVersion2</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:accessDate>2018-04-05T12:58:07</core:accessDate>
   </core:heading>
   <mapVersion xmlns="http://schema.omg.org/spec/CTS2/1.0/MapVersion" documentURI="UNKNOWN" mapVersionName="ExampleMappingVersion2" about="urn:negros:oid#745e7fdc_3A16294ff1eea_3A_2D7f29">
       <core:sourceAndNotation xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" />
       <versionOf uri="example:mapping">UNKNOWN</versionOf>
       <fromCodeSystemVersion>
           <core:version xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">1.0</core:version>
           <core:codeSystem xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" uri="example:terminology">ExampleCS2013</core:codeSystem>
       </fromCodeSystemVersion>
       <toCodeSystemVersion>
           <core:version xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">1.0</core:version>
           <core:codeSystem xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" uri="example:anotherTerminology">ExampleCS2016</core:codeSystem>
       </toCodeSystemVersion>
       <versionTag>
           <core:mapVersion xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">2.0</core:mapVersion>
       </versionTag>
       <entries>http://localhost:8080/WebCts2LE/rest/map/_/mapversion/ExampleMappingVersion2/entries</entries>
   </mapVersion>
</MapVersionMsg>


Retrieve map entries of a specific map version

  • MapEntryQueryService:resolve: Return a directory containing a summary of the map entries referenced by directory that meet any additional requirements from context. e.g. To request the entries of the map version with uri "example:mapping" and version id "2.0" the following call has to be formulated: /rest/map/_/mapversion/2.0/entries?mapuri=example:mapping
  • Path: /map/{mapid}/mapversion/{mapversionid}/entries
  • Method: GET
  • Path Parameters:
mapid the Name of the Map - this parameter will be ignored; it should always be set to '_'
mapversionid if the query parameter mapuri is given, the value of this parameter defines the version ID (set to '_def' to request the default version); if the query parameter mapuri is NOT given, the value of this parameter refers to the unique resourceID of the map version
  • Query Parameters:
mapuri the URI, OID or alternateID of the mapping, e.g. www.examplemapping.de; use this query parameter in conjunction with the path parameter mapversionid when the latter refers to the versionID of the requested value set definition
page the 0-based page number used for paging result sets. Default is 0.
maxtoreturn the maximum number of entries that may be present in a return Directory. If maxToReturn is not supplied, a block size of 100 is used.
  • returns: mapVersion:MapEntryList

Example Response

API Paths

  • a.) fetch by uri and version id: /map/_/mapversion/2.0/entries?mapuri=example:mapping
  • b.) fetch by resourceID: /map/_/mapversion/ExampleMappingVersion2/entries

The responses of a and b only differ in terms of their <core:heading> element. Find below the response when requesting with path b. 

<?xml version="1.0" encoding="UTF-8"?>
<MapEntryList xmlns="http://schema.omg.org/spec/CTS2/1.0/MapVersion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" complete="COMPLETE" numEntries="1">
   <core:heading xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">
       <core:resourceRoot>http://localhost:8080/WebCts2LE/rest/</core:resourceRoot>
       <core:resourceURI>map/_/mapversion/ExampleMappingVersion2/entries</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</core:val>
       </core:parameter>
       <core:parameter arg="page">
           <core:val>0</core:val>
       </core:parameter>
       <core:parameter arg="maxtoreturn">
           <core:val>100</core:val>
       </core:parameter>
       <core:accessDate>2018-04-05T13:11:24</core:accessDate>
   </core:heading>
   <entry xmlns="http://schema.omg.org/spec/CTS2/1.0/MapVersion">
       <entry processingRule="ALL_MATCHES">
           <assertedBy>
               <core:mapVersion xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">ExampleMappingVersion2</core:mapVersion>
               <core:map xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core" uri="example:mapping" />
           </assertedBy>
           <mapFrom uri="urn:negros:oid#745e7fdc_3A16294ff1eea_3A_2D7ffd">
               <core:name xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">a01</core:name>
           </mapFrom>
           <mapSet processingRule="ALL_MATCHES" entryOrder="1">
               <mapTarget entryOrder="1">
                   <mapTo uri="urn:negros:oid#745e7fdc_3A16294ff1eea_3A_2D7f41">
                       <core:name xmlns:core="http://schema.omg.org/spec/CTS2/1.0/Core">a02</core:name>
                   </mapTo>
                   <correlation>SPECIALISES</correlation>
               </mapTarget>
           </mapSet>
       </entry>
   </entry>
</MapEntryList>

Exceptions

  • UnknownMap if
    • the name of the map (path parameter mapid) is not set to an underscore
    • the query parameter mapuri is not specified or is not an uri
    • there is no map version with the given uri and version id
Abgerufen von „https://websites.fraunhofer.de/CTS2-LE/index.php?title=CTS2-LE_REST_API:_Read_Maps_and_Map_Versions&oldid=1076“