CTS2-LE REST API: Read Maps and Map Versions

Aus CTS2-LE
Zur Navigation springen Zur Suche springen

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

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 map entries for a specific map

  • 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 the Name of the Map Version
  • 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:MapEntryList

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

<?xml version="1.0" encoding="UTF-8"?>
<MapEntryList xmlns="http://www.omg.org/spec/CTS2/1.1/MapVersion" 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>map/_/mapversion/2.0/entries</core:resourceURI>
       <core:parameter arg="Accept">
           <core:val>*/*</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-18T15:49:05</core:accessDate>
   </core:heading>
   <entry xmlns="http://www.omg.org/spec/CTS2/1.1/MapVersion">
       <entry processingRule="ALL_MATCHES">
           <assertedBy>
               <core:mapVersion xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">ExampleMappingVersion2</core:mapVersion>
               <core:map xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core" uri="example:mapping" />
           </assertedBy>
           <mapFrom uri="urn:negros:oid#_2D6965a103_3A155e86bd661_3A_2D7ffd">
               <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">a01</core:name>
               <core:designation xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">aPrefTerm</core:designation>
           </mapFrom>
           <mapSet processingRule="ALL_MATCHES" entryOrder="1">
               <mapTarget entryOrder="1">
                   <mapTo uri="urn:negros:oid#_2D6965a103_3A155e86bd661_3A_2D7fa8">
                       <core:name xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">a02</core:name>
                       <core:designation xmlns:core="http://www.omg.org/spec/CTS2/1.1/Core">aPrefTerm</core:designation>
                   </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=451“