ExampleTapirMessages < TAPIR

r36 - 22 Dec 2008 - 18:14:58 - RenatoDeGiovanniYou are here: TWiki >

TAPIR Web > ExampleTapirMessages

This section provides some examples of common TAPIR messages. The latest version of the examples can always be found in the subversion repository. This page is only updated once in a while, so it might be that the examples below are not valid against the latest schema. But they will only vary in minor details.

http://ww2.biocase.org/svn/tapir/trunk/protocol/examples/

Messages in TAPIR should be sent through HTTP. Every TAPIR message can be sent as an XML encoded document as defined by the TAPIR schema or alternatively through a list of URL parameters specified by TAPIR as well.

This allows to invoke all TAPIR operations through HTTP GET (using the parameters) or trough HTTP POST (using parameters or sending an XML document).

Here we provide a parameterized version of every example and the corresponding XML version. They MUST generate the same result from a TAPIR compliant service. The parameterized version is represented with an*unencoded* URL string.

TAPIR Operations

Ping operation

HTTP Parameters

http://wrapper_end_point?op=ping

XML message

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00">
            <software name="TAPIR_Implementation" version="1.0"/>
        </source>
        <destination>http://accesspoint_url</destination>
    </header>
    <ping/>
</request>

Response

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://accesspoint_url" sendtime="2005-11-11T12:23:57.023+01:00"></source>
    </header>
    <pong/>
</response>

Metadata operation

HTTP Parameters

http://wrapper_end_point?op=metadata

XML message

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00">
        </source>
    </header>
    <metadata/>
</request>

Response

<?xml version='1.0' encoding='utf-8'?>
<metadata xmlns='http://rs.tdwg.org/tapir/1.0' xmlns:dc='http://purl.org/dc/elements/1.1/' xmlns:dct='http://purl.org/dc/terms/' xmlns:geo='http://www.w3.org/2003/01/geo/wgs84_pos#' xmlns:vcard='http://www.w3.org/2001/vcard-rdf/3.0#'>
  <dc:title>BioCASe training</dc:title>
  <dc:type>http://purl.org/dc/dcmitype/Service</dc:type>
  <accesspoint>http://localhost:8080/tapir/pywrapper/training</accesspoint>
  <dc:description>This testing database is used in BioCASE workshops and other events.
    This database was gratefully provide by the Herbarium at the Universidad of Barcelona CeDocBiv, 
    but the data has been greatly modified so DO NOT CONSIDER IT AS REAL DATA
  </dc:description>
  <dc:language>en-us</dc:language>
  <dc:subject>BioCASe, Barcelona, CeDocBiv, herbarium, plantae, specimen</dc:subject>
  <dct:bibliographicCitation>The BioCASE training database</dct:bibliographicCitation>
  <dc:rights>You can distribute this database freely but only for testing purposes and training.</dc:rights>
  <dct:modified>2005-03-17</dct:modified>
  <indexingPreferences frequency='P14D' maxDuration='PT3H' startTime='02:00:00Z'/>
  <relatedEntity>
    <role>data supplier</role>
    <role>data supplier</role>
    <entity>
      <identifier>http://ww3.bgbm.org/biocase/datasources/training/metadata.xml</identifier>
      <name>Botanic Garden &amp; Botanical Museum Berlin-Dahlem</name>
      <acronym>BGBM</acronym>
      <logoURL>http://www.biocase.org/images/bdi_logo.gif</logoURL>
      <description>The Botanic Garden Berlin-Dahlem comprises an area of 126 acres and hence is one of the worldŽs largest and most important gardens. About 22,000 different species of plants are cultivated here. In the 39 acres of the plant-geography section - one of the biggest of its kind in the world - you can travel all the way around the Northern Hemisphere, and in the 42 acre Arboretum and taxonomy section you can get an insight into the relationship among woody and herbaceous plants. The greenhouse complex consists of 16 houses open to the public and offers the possibility to travel through tropical and subtropical vegetation. These living collections, along with the preserved collections, form the basis for the continued expansion of scientific study within the plant kingdom, with the goal to deepen the knowledge necessary for the utilization and protection of plant diversity on earth.</description>
      <address>Königin-Luise-Straße 6-8, D-14191 Berlin, Germany</address>
      <relatedInformation>http://www.bgbm.org/</relatedInformation>
      <hasContact>
        <role>technical</role>
        <vcard:VCARD>
          <vcard:FN>Frank Sinatra</vcard:FN>
          <vcard:TITLE>senior developer</vcard:TITLE>
          <vcard:TEL>+49 30-5555-55</vcard:TEL>
          <vcard:EMAIL>frank@worldstars.org</vcard:EMAIL>
        </vcard:VCARD>
      </hasContact>
      <hasContact>
        <role>administrative</role>
        <vcard:VCARD>
          <vcard:FN>Frankenstein</vcard:FN>
          <vcard:TITLE>head of biodiversity department</vcard:TITLE>
          <vcard:TEL>+49 30-5555-56</vcard:TEL>
          <vcard:EMAIL>fstein@worldstars.org</vcard:EMAIL>
        </vcard:VCARD>
      </hasContact>
      <geo:Point>
        <geo:lat>52.458356</geo:lat>
        <geo:long>13.305017</geo:long>
      </geo:Point>
    </entity>
  </relatedEntity>
</metadata>

Capabilities operation

HTTP Parameters

http://wrapper_end_point?op=capabilities

XML message

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00">
        </source>
    </header>
        <capabilities/>
</request>

Response

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://accesspoint_url" sendtime="2005-11-11T12:23:56.023+01:00">
            <software name="TAPIR_Implementation" version="1.0"/>
        </source>
    </header>
    <capabilities>
        <operations>
            <ping/>
            <metadata/>
            <capabilities/>
            <view>
                <queryTemplates>
                    <queryTemplate location="http://url_to_searchtemplateA"/>
                    <queryTemplate location="http://url_to_searchtemplateB"/>
                    <queryTemplate location="http://url_to_inventorytemplate"/>
                </queryTemplates>
            </view>
            <inventory/>
            <search>
                <staticOutputModels>
                    <outputModel location="http://url_to_raw_outputmodelA"/>
                    <outputModel location="http://url_to_raw_outputmodelB"/>
                </staticOutputModels>
            </search>
        </operations>
        <filter>
            <encoding>
                <expression>
                    <concept/>
                    <literal2/>
                    <parameter/>
                    <variable/>
                    <arithmetic>
                        <add/>
                        <sub/>
                    </arithmetic>
                </expression>
                <booleanOperators>
                    <logical>
                        <not/>
                        <and/>
                        <or/>
                    </logical>
                    <comparative>
                        <equals/>
                        <greaterThan/>
                        <greaterThanOrEquals/>
                        <lessThan/>
                        <lessThanOrEquals/>
                        <in/>
                        <isNull/>
                        <like/>
                    </comparative>
                </booleanOperators>
            </encoding>
        </filter>
        <concepts>
            <conceptNameServers>
                <server location="http://url_to_primary_concept_server"/>
                <server location="http://url_to_secondary_concept_server"/>
            </conceptNameServers>
            <schema namespace="http://www.tdwg.org/schemas/abcd/1.2"
                location="http://www.bgbm.org/TDWG/CODATA/Schema/ABCD-1.20.xsd">
                <mappedConcept
                    id="/DataSets/DataSet/DatasetDerivations/DatasetDerivation/DateSupplied"
                    searchable="true"/>
                <mappedConcept
                    id="/DataSets/DataSet/DatasetDerivations/DatasetDerivation/Description"
                    searchable="true"/>
            </schema>
            <schema namespace="http://digir.net/schema/conceptual/darwin/extension/curatorial/1.0"
                location="http://digir.net/schema/conceptual/darwin/extension/curatorial/1.0/curatorialWithDiGIRv1.3.xsd">
                <mappedConcept id="/CatalogNumberNumeric" searchable="true" mandatory="true"/>
                <mappedConcept id="/IdentifiedBy" searchable="true"/>
            </schema>
        </concepts>

        <variables>
            <environment>
                <timestamp/>
                <lastUpdate/>
                <date/>
                <datasourceName/>
                <accessPoint/>
            </environment>
        </variables>
        
        <settings>
            <minQueryTermLength>2</minQueryTermLength>
            <maxElementRepetitions>10</maxElementRepetitions>
            <maxElementLevels>20</maxElementLevels>
            <maxResponseTags>500</maxResponseTags>
            <maxResponseSize>500</maxResponseSize>
        </settings>
        
    </capabilities>
</response>

Inventory operation

HTTP Parameters

Inventory template An inventory template can be referred to in a request and allows simple parameter bindings to a more complex operation. Example template:

<?xml version="1.0" encoding="UTF-8"?>
<inventoryTemplate xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <label>Specimen Names</label>
    <documentation>Search and list unique scientific names of specimen identifications ordered
        alphabetically by their name. The filter parameter "name" is used to build the filter</documentation>
    <concepts>
        <concept id="dwc:/ScientificName"/>
    </concepts>
    <filter>
        <like>
            <concept id="dwc:/ScientificName"/>
            <parameter name="name"/>
        </like>
    </filter>
</inventoryTemplate>

XML message In the XML messages aliases could also be used, but we only shows here the example with complete concept IDs

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00">
        </source>
    </header>
    <inventory count="false" limit="100" start="0">
        <concepts>
            <concept id="http://digir.net/schema/conceptual/darwin/2003/1.0#/Country"/>
            <concept id="http://digir.net/schema/conceptual/darwin/2003/1.0#/Genus"/>
        </concepts>
    </inventory>
</request>

Response

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://accesspoint_url" sendtime="2005-11-11T12:23:56.023+01:00">
            <software name="TAPIR_Implementation" version="1.0"/>
        </source>
    </header>
    <inventory>
        <concepts>
            <concept id="http://digir.net/schema/conceptual/darwin/2003/1.0#/Country"/>
            <concept id="http://digir.net/schema/conceptual/darwin/2003/1.0#/Genus"/>
        </concepts>
        <record>
            <value>AUSTRALIA</value>
            <value>Calicium</value>
        </record>
        <record>
            <value>AUSTRALIA</value>
            <value>Fellhanera</value>
        </record>
        <summary start="1" totalReturned="2" totalMatched="15" next="3"/>
    </inventory>
</response>

Search operation

Search operations make use of output models.

HTTP Parameters

Without aliases
http://wrapper_end_point?op=search&start=0&limit=10&model=http://res.tdwg.org/tapir/models/abcd206.xml&filter=http://www.tdwg.org/schemas/abcd/2.06/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString like "Luzu*"&orderby=http://www.tdwg.org/schemas/abcd/2.06/DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString
With global concept aliases
http://wrapper_end_point?op=search&start=0&limit=10&model=http://res.tdwg.org/tapir/models/abcd206.xml&filter=FullScientificName@abcd206 like "Luzu*"&orderby=FullScientificName@abcd206
With template
http://wrapper_end_point?op=search&start=0&limit=10&template=http://you.net/search3.xml&name=Luzu*

Output Model

<?xml version="1.0" encoding="UTF-8"?>
<outputModel xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://rs.tdwg.org/tapir/1.0
        http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd
        http://www.w3.org/2001/XMLSchema
        http://www.w3.org/2001/XMLSchema.xsd">
    <structure>
        <xs:schema targetNamespace="http://example.net/simple_specimen">
            <xs:element name="dataset">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="specimen" minOccurs="0" maxOccurs="unbounded">
                            <xs:complexType>
                                <xs:sequence>
                                    <xs:element name="identification" maxOccurs="unbounded"
                                        minOccurs="0">
                                        <xs:complexType>
                                            <xs:sequence>
                                                <xs:element name="name">
                                                    <xs:complexType>
                                                        <xs:simpleContent>
                                                            <xs:extension base="xs:string">
                                                                <xs:attribute name="family"
                                                                    type="xs:string"/>
                                                            </xs:extension>
                                                        </xs:simpleContent>
                                                    </xs:complexType>
                                                </xs:element>
                                                <xs:element name="identifier" type="xs:string"
                                                    minOccurs="0"/>
                                            </xs:sequence>
                                            <xs:attribute name="date" type="xs:string"
                                                use="optional"/>
                                        </xs:complexType>
                                    </xs:element>
                                </xs:sequence>
                                <xs:attribute name="catnum" type="xs:int" use="required"/>
                            </xs:complexType>
                        </xs:element>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:schema>
    </structure>
    <indexingElement path="/dataset/specimen"/>
    <mapping>
        <node path="/dataset/specimen@catnum">
            <concept id="dwc:/CatalogNumber"/>
        </node>
        <node path="/dataset/specimen/identification/name">
            <concept id="dwc:/ScientificName"/>
        </node>
        <node path="/dataset/specimen/identification/name@family">
            <concept id="dwc:/Family"/>
        </node>
        <node path="/dataset/specimen/identification/identifier">
            <concept  id="abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/Identifier/IdentifierPersonName/PersonName"/>
        </node>
        <node path="/dataset/specimen/identification@date">
            <concept  id="abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/IdentificationDate/DateText"/>
        </node>
    </mapping>
</outputModel>

Search template A search template can be referred to in a request and allows simple parameter bindings to a more complex operation. Example template:

<?xml version="1.0" encoding="UTF-8"?>
<searchTemplate xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <label>Specimen by Name</label>
    <documentation>Search specimens by their scientific name. Result is returned ordered by name and
        catalogue number. The filter parameter "name" is used to build the filter.</documentation>
    <outputModel location="http://the.same.host/output_model1.xml"/>
    <filter>
        <like>
            <concept id="dwc:/ScientificName"/>
            <parameter name="name"/>
        </like>
    </filter>
    <orderBy>
        <concept id="dwc:/ScientificName"/>
        <concept id="dwc:/CatalogNumber"/>
    </orderBy>
</searchTemplate>

XML message

<?xml version="1.0" encoding="UTF-8"?>
<request xmlns="http://rs.tdwg.org/tapir/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
    file:/Users/javi/workspace/tapirProtocol/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00"/>
    </header>
    <search start="0" limit="10">
        <outputModel
            location="http://ww2.biocase.org/svn/tapir/trunk/protocol/examples/output_model1.xml"/>
        <filter>
            <like>
                <concept id="dwc:/ScientificName"/>
                <literal2 value="Luzu*"/>
            </like>
        </filter>
        <orderBy>
            <concept id="dwc:/Family"/>
            <concept id="dwc:/ScientificName"/>
        </orderBy>
    </search>
</request>

Response

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://rs.tdwg.org/tapir/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/tapir/1.0
    http://ww2.biocase.org/svn/tapir/trunk/protocol/tapir.xsd">
    <header>
        <source accesspoint="http://url_from_client" sendtime="2005-11-11T12:23:56.023+01:00"/>
    </header>
    <search>
        <dataset xmlns="http://example.net/simple_specimen"
            xsi:schemaLocation="http://example.net/simple_specimen
            http://ww2.biocase.org/svn/tapir/trunk/protocol/examples/schema_used_in_output_model.xsd">
            <specimen catnum="234">
                <identification>
                    <name>Luzula luzuloides</name>
                </identification>
            </specimen>
            <specimen catnum="290">
                <identification>
                    <name>Luzula alpestris</name>
                </identification>
            </specimen>
        </dataset>
        <summary start="0" totalReturned="2"/>
    </search>
</response>

TDWG Wiki > TAPIR

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback