src/site/apt/rest-api.apt

   1                         ------
   2                         REST API
   3                         ------
   4                         ------
   5                         2010-11-17
   6                         ------
   7
   8
   9 REST API
  10
  11         The CDM REST API is a {{{http://en.wikipedia.org/wiki/Representational_State_Transfer} RESTful}} interface to resources stored in the {{{./index.html#The_Common_Data_Model_-_CDM}CDM}}. The RESTful architecture allows accessing the various resources like Taxa, Names, References, Media, etc by stable URIs. Due to security constraints and to assure the integration of data, currently only read operations (= HTTP GET) are permitted, {{{http://dev.e-taxonomy.eu/trac/wiki/CdmServerReadWriteRest} write operations}} will be available in the near future.
  12
  13         The architecture directly exposes domain model entities, i.e. it provides direct serializations of the objects as they are stored in the CDM whereever possible. For the external representations, like LSIDs and TDWG data exchange schema like TCS however using DTOs is unavoidable. The {{{API_Service}API Service}} provides an easy to use way to transfer CDM data to web based clients. The {{{Portal_Service} Portal Service}} is a specialization as needed by {{{http://wp5.e-taxonomy.eu/portal}CDM Dataportal}} that adds some fields like localized representations to the pure CDM entities.
  14
  15         <Table of Contents>
  16
  17 %{toc|section=1|fromDepth=2|toDepth=4}
  18
  19
  20
  21
  22
  23 * Service Sections
  24
  25         The CDM REST Services architecture is functionally separated into four different parts:
  26
  27         * The <<API Service>> a clean RESTful bit, which will expose data in a modular, normalized way. It is a more-or-less one-to-one concordance between URIs and service api methods.
  28
  29         * The <<Portal Service>> which is specially taliored for the needs of dataportals which will primarily display "Species Page". Thus this service will be provide denormalized pages which contain a specific assemblys of information.
  30
  31         * The <<External Services>> are supporting non CDM applications and services like for example a map generation service, LSID Services.
  32
  33         * The <<Classification Service>> exposes special DTOs which combine data from the <<<TaxonBase>>>, <<<TaxonNode>>> and from the <<<Classification>>> entities.
  34
  35         []
  36
  37         Detailed descriptions of the services are available in {{{Service_Descriptions} Service Descriptions}} below.
  38
  39
  40
  41
  42 * Object Boundaries
  43
  44         Nearly all CDM entities are related to each other more or less dicrectly or indirectly and thus forming a huge object graph. A web services however should only deliver a specific object perhaps with some attached associated objects, so it id crucial to draw the line quite sensible between the objects in question and the full object graph. The CDM Service solves this by selectively initializing CDM entities.
  45
  46         The primary idea is that the <<API Service>> delivers the requested object with all its *toOne relations. Associated objects of the requested object which are at the many side of the *toMany relations are available through URIs which map the fieldname of the *toMany relation. Transient fields are not serialized except of the <<<titleCache>>> property, this one and serialized and thus initialized for each <<<IdentifiableEntity>>>. The initialization of the <<<titleCache>>> property is performed by the <<<CacheStrategie>>> of the specific cdm class and usually spans multiple associated entities of variable depth of object nesting.
  47
  48         In contrast the <<Portal Service>>, often adds *toMany relations and transient fields to the requested objects. It even may deliver sub object graphs with a depth of an arbitrary number of levels for specific branches.
  49
  50         The extend of objects, i.e the initialization depth of CDM entities is documented in {{{Service_Descriptions} Service Descriptions}} below. The extend is explained using a <property path syntax> which indicates the properties and transient getters of a specific CDM entity bean which are being initialized by the service.
  51
  52         * Simple (name) - The specified name identifies an individual property of a particular CDM entity bean. The name of the actual getter method is determined using standard !JavaBeans instrospection, so that a property named "xyz" will have a getter method named getXyz() or (for boolean properties only) isXyz(), and a setter method named setXyz().
  53
  54         * Nested (name1.name2.name3) The first name element is used to select a property getter, as for simple references above. The object returned for this property is then consulted, using the same approach, for a property getter for a property named name2, and so on. The property value that is ultimately retrieved or modified is the one identified by the last name element.
  55
  56         * Indexed (name[index]) - The underlying property value is assumed to be an array, or this !JavaBean is assumed to have indexed property getter and setter methods. The appropriate (zero-relative) entry in the array is selected. List objects are now also supported for read/write. You simply need to define a getter that returns the List
  57
  58         * \*toOne-Wildcard ($) This wildcard is used to select all property getters which reference to one associated bean. A wildcard subsequently terminates a 'property path'.
  59
  60         * \*toAny-Wildcard (*) This wildcard is used to select all property getters which reference to one associated bean and to to many associated bean. A wildcard subsequently terminates a 'property path'.
  61
  62         * Combined (name1.name2[index].$) - Combining mapped, nested, and indexed and wildcard references is also supported.
  63
  64         []
  65
  66         This syntax description partially is lend from {{{http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/org/apache/commons/beanutils/PropertyUtilsBean.html} Apache Commons BeanUtils}}
  67
  68         In fact the actual extend of serialized CDM entities may exceed the extend indicated by the property path syntax. This especially happens when a transient getter is to be initialized. Due to potential internal logic in the transient getter it is unpredictable which properties actually are being initialized when only looking at the property path. A common candidate for this is the <<<getTaggedName()>>> property of {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/name/TaxonNameBase.html} TaxonNameBase}}.
  69
  70
  71         <Developer Hints>:
  72
  73         The initialization od CDM entities is performed by implementations of the  {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/persistence/dao/BeanInitializer.html} BeanInitializer}} interface. In order to find out more on this topic please refer to {{{http://dev.e-taxonomy.eu/trac/wiki/CdmEntityInitalization} CDM Entity Initialization}}.
  74
  75
  76
  77
  78
  79 * Localization
  80
  81         In order to provide the client with localized resources all services respect the {{{http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4} Accept-Language HTTP header}}.
  82         For example the Portal service returns localized representations according to the Language tags supplied in the  Accept-Language HTTP header.
  83 The service tries finding the best matching representation. If no representation in any preferred language is found the service falls back to return the representation in {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/Language.html#DEFAULT()} Default Language}} and if necessary further falls back to return the first representation found if any exists.
  84
  85         Instances of the folowing CDM classes or subclasses of them potentially have multiple internationalized representations in different languages:
  86
  87         * <{{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/TermBase.html} TermBase}}> - language dependent representation through {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/Representation.html} Representation}}; The localized reresentation string is added to the TermBase entities by adding the aaditional field: <representation_L10n>.
  88
  89         * <{{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/description/TextData.html} TextData}}> - language dependent representation through {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/MultilanguageText.html} MultilanguageText}}; The localized multilanguage text string is added to the TextData entities by adding the aaditional field: <multilanguageText_L10n>.
  90
  91         []
  92
  93         Localization is handeled a bit differently by various service sections the {{{API_Service} API Service}} just adds the localized representations. The {{{Portal_Service} Portal Service}} which focuses in representation, not only adds the localized representations but also hides the {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/Representation.html} Representation}} or {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/model/common/MultilanguageText.html} MultilanguageText}} fields from serialization in order to reduce complexity and to improve performance.
  94
  95         <Developer Hints>
  96
  97         Classes involved in Content Localization:
  98
  99         * {{{http://wp5.e-taxonomy.eu/cdmlib/apidocs/eu/etaxonomy/cdm/remote/controller/interceptor/LocaleContextHandlerInterceptor.html} LocaleContextHandlerInterceptor}}
 100 Configuration in:
 101
 102         * {{{http://dev.e-taxonomy.eu/svn/trunk/cdmlib/cdmlib-remote-webapp/src/main/webapp/WEB-INF/cdmrest-servlet.xml} WEB-INF/cdmrest-servlet.xml}}
 103
 104
 105
 106
 107 * Content Negotiation
 108
 109         There are two ways to demand a special content type:
 110
 111         [[1]] by file extension (*.json or *.xml)
 112
 113         [[1]] by {{{http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1} Accept HTTP request header}} - Accepted mime types are: <<<application/json>>>, <<<text/xml>>>
 114
 115         []
 116
 117         Default: XML
 118
 119         The CDM REST API primarily trys using the file extension, then the Accept HTTP request header is taken into account. If whether the file extension or not the  Accept HTTP request header specify valid content types the default XML will be used.
 120
 121         <Developer Hints>
 122
 123         Classes involved in Content Negotiation:
 124
 125         * {{{http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/servlet/view/ContentNegotiatingViewResolver.html} org.springframework.web.servlet.view.ContentNegotiatingViewResolver}}
 126
 127         []
 128
 129         Configuration files involved:
 130
 131         * {{{http://dev.e-taxonomy.eu/svn/trunk/cdmlib/cdmlib-remote-webapp/src/main/webapp/WEB-INF/cdmrest-servlet.xml} WEB-INF/cdmrest-servlet.xml}}
 132
 133
 134
 135
 136 * Character Encoding
 137
 138         All data is returned in UTF-8 character encoding.
 139
 140
 141
 142
 143 * Service Descriptions
 144
 145         The syntax of the mapped service URIs contains the the \{datasource-bean-name\} path element. The available \{datasource-bean-name\}s are taken from a configuration file which is loaded by the CDM-Server during startup. The "datasources.xml" file is loaded by default from the following locations depending on the operation system in which the cdm-server is installed:
 146
 147         * Linux: <<</opt/cdm-server/.cdmLibrary/datasources.xml>>>
 148
 149         * Windows: <<<"%PROGRAMFILES%/EDIT CDM-Server/.cdmLibrary/datasources.xml">>>
 150
 151         []
 152
 153         The actual location of the "datasources.xml" can specified and thus be overridden using a specific commandline parameter for EDIT CDM-Server. For more information please refer to the {{{http://wp5.e-taxonomy.eu/cdm-server} CDM Community Server documentation}}.
 154
 155
 156         <NOTE:>
 157
 158         [[1]] Former versions of the EDIT CDM-Server where using <<<\{USER_HOME\}./cdmLibrary/datasources.xml>>> this is now being only used by the EDIT Taxonomic Editor.
 159
 160         [[1]] The <<<UpdatableRoutingDataSource>>> is no longer being used by the EDIT CDM-Server.
 161
 162
 163
 164
 165 ** API Service
 166
 167         The are a clean RESTful webservice, which will expose data in a modular, normalized way.
 168 It is a more-or-less one-to-one concordance between URIs and service api methods.
 169 Due to its generic architecture the URIs are also generic and follow a common pattern which is repeated in each controller.
 170 In the following the generic URIs are documented first followed by type specific implementations. The pathelement \{base-type\} is frequently used in generid URIs.
 171
 172         <Valid Values for \{base-type\} are>:
 173
 174         * <<agent>>: Service URIs returning AgentBase or sub type entities.
 175
 176         * <<description>>: Service URIs returning DescriptionBase or sub type entities.
 177
 178         * <<feature>>: Service URIs returning DescriptionBase or sub type entities
 179
 180         * <<media>>: Service URIs returning Media or sub type entities
 181
 182         * <<name>>: Service URIs returning TaxonNameBase or sub type entities
 183
 184         * <<occurrence>>: Service URIs returning SpecimenOrObservationBase or sub type entities
 185
 186         * <<reference>>: Service URIs returning ReferenceBase or sub type entities
 187
 188         * <<taxon>>: Service URIs returning TaxonBase or sub type entities
 189
 190         * <<term>>: Service URIs returning DefinedTermBase or sub type entities
 191
 192         []
 193
 194         Most services are using the <<default initialisation strategy>> which is:
 195
 196 ----
 197 "$"
 198 ----
 199
 200 *** /\{base-type\}/
 201
 202         Depending on the URI parameters used, this service returns either a Pager on or a List of the \{base-type\} entities identified by the \{uuid\}.
 203 The returned \{base-type\} instances are initialized by the <default initialisation strategy>.
 204
 205         <URI Parameters to return a Pager>:
 206
 207         * <pageNumber> the number of the page to be returned, the first page has the pageNumber = 1 - <optional parameter>
 208
 209         * <pageSize> the maximum number of entities returned per page (can be null to return all entities in a single page) - <optional parameter>
 210
 211         * <type>  Further restricts the type of entities to be returned. If null the type mapped by \{base-type\} is being used. - <optional parameter>
 212
 213         []
 214
 215         <URI Parameters to return a List>:
 216
 217         * <start> The offset index from the start of the list. The first entity has the index = 0 - <required parameter> <<The start parameter is used to distinguish between the List and Pager variants!>>
 218
 219         * <limit> The maximum number of entities returned. - <optional parameter>
 220
 221         * <type> Further restricts the type of entities to return. If null the type mapped by \{base-type\} is being used. - <optional parameter>
 222
 223
 224 *** /\{base-type\}/name/\{uuid\}
 225
 226         Get the \{base-type\} entity identified by the \{uuid\}.
 227
 228         <Returns:>
 229
 230         The returned \{base-type\} entity is initialized by the <default initialisation strategy>.
 231
 232 *** /\{base-type\}/name/\{uuid\}/annotation
 233
 234         Get the a Pager on the Annotations for the \{base-type\} entity identified by the \{uuid\}.
 235
 236         <Returns:>
 237
 238         Pager on the Annotations for the \{base-type\} entity identified by the \{uuid\}.
 239         The returned \{base-type\} entity are initialized by the <default initialisation strategy>.
 240
 241
 242
 243 *** /name/\{name-uuid\}/typeDesignations
 244
 245         Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the \{name-uuid\}.
 246
 247         <Returns:>
 248
 249         A list of TypeDesignationBase entities which are initialized using the following initialization strategy:
 250
 251 ----
 252 "$",
 253 "citation.authorTeam",
 254 "typifiedNames.taggedName"
 255 ----
 256
 257 *** /taxon/\{taxon-uuid\}/accepted
 258
 259         Get the set of accepted Taxon entities for a given \{@link TaxonBase\} entity identified by the <code>\{taxon-uuid\}</code>.
 260
 261         <Returns:>
 262
 263         A set of Taxon entities which are initialized using the <default initialisation strategy>..
 264
 265 ** Portal Service
 266
 267 *** /portal/name/\{name-uuid\}
 268
 269         The TaxonNameBase instance identified by the \{name-uuid\}.
 270         The returned TaxonNameBase is initialized by the following strategy
 271
 272
 273 *** /portal/name/\{name-uuid\}/descriptions
 274
 275         Get the list of TaxonNameDescriptions of the Name associated with the TaxonNameBase instance identified by the \{name-uuid\}.
 276
 277         <Returns:>
 278
 279         A list of TaxonNameDescription entities which are initialized using the following initialization strategy:
 280
 281 ----
 282 "uuid",
 283 "feature",
 284 "elements.$",
 285 "elements.multilanguageText",
 286 "elements.media.representations.parts"
 287 ----
 288
 289 *** /portal/name/\{name-uuid\}/typeDesignations
 290
 291         Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the \{name-uuid\}.
 292
 293         <Returns:>
 294
 295         A list of TypeDesignationBase entities which are initialized using the following initialization strategy:
 296
 297 ----
 298 "citation.authorTeam",
 299 "typeName.$",
 300 "typeName.taggedName",
 301 "typeStatus.representations",
 302 "typeSpecimen.media.representations.parts"
 303 ----
 304
 305
 306 *** /portal/taxon/\{taxon-uuid\}
 307
 308         Get the TaxonBase instance identified by the \{taxon-uuid\}.
 309         The returned Taxon is initialized by the following strategy TAXON_INIT_STRATEGY
 310
 311 ----
 312 "*",
 313 "relationsToThisName.fromTaxon.name.taggedName",
 314 "name.$",
 315 "name.taggedName",
 316 "name.rank.representations",
 317 "name.status.type.representations",
 318 "descriptions.elements.$",
 319 "descriptions.elements.area",
 320 "descriptions.elements.area.$",
 321 "descriptions.elements.multilanguageText",
 322 "descriptions.elements.media.representations.parts",
 323 ----
 324
 325 *** /portal/taxon/find
 326
 327         Find Taxa, Synonyms, Common Names by name, either globally or in a specific geographic area.
 328
 329         <URI Parameters:>
 330
 331         * <<query>> the string to query for. Since the wildcard character '*' internally always is appended to the query string, a search always compares the query string with the beginning of a name. - <required parameter>
 332
 333         * <<treeUuid>> the UUID of a TaxonomicTree to which the search is to be restricted. - <optional parameter>
 334
 335         * <<areas>> restrict the search to a set of geographic NamedAreas. The parameter currently takes a list of TDWG area labels.  - <optional parameter>
 336
 337         * <<page>> the number of the page to be returned, the first page has the pageNumber = 1 - <optional parameter>
 338
 339         * <<pageSize>> the maximum number of entities returned per page (can be null to return all entities in a single page) - <optional parameter>
 340
 341         * <<doTaxa>> weather to search for instances of Taxon - <optional parameter>
 342
 343         * <<doSynonyms>> weather to search for instances of Synonym - <optional parameter>
 344
 345         * <<doTaxaByCommonNames>> for instances of Taxon by a common name used - <optional parameter>
 346
 347         []
 348
 349         <Returns:>
 350
 351         A pager on a list of IdentifiableEntitys initialized by the following strategy:
 352
 353 ----
 354 "*",
 355 "relationsToThisName.fromTaxon.name.taggedName",
 356 "name.$",
 357 "name.taggedName",
 358 "name.rank.representations",
 359 "name.status.type.representations"
 360 ----
 361
 362 *** /portal/taxon/\{taxon-uuid\}/synonymy
 363
 364         Get the synonymy for a taxon identified by the \{taxon-uuid\}. The synonymy consists of two parts: The group of homotypic synonyms of the taxon and the heterotypic synonymy groups of the taxon. The synonymy is ordered historically by the type designations and by the publication date of the nomenclatural reference
 365
 366         <Returns:>
 367
 368         A map with to entries which are mapped by the following keys: "homotypicSynonymsByHomotypicGroup", "heterotypicSynonymyGroups", containing lists of Synonyms which are initialized using the following initialization strategy:
 369
 370 ----
 371 "synonymRelations.$",
 372 "synonymRelations.synonym.$",
 373 "synonymRelations.synonym.name.taggedName",
 374 "synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
 375 "synonymRelations.synonym.name.nomenclaturalReference.inJournal",
 376 "synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
 377 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
 378 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
 379 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
 380 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
 381
 382 "name.homotypicalGroup.$",
 383 "name.homotypicalGroup.typifiedNames.$",
 384 "name.homotypicalGroup.typifiedNames.name.taggedName",
 385
 386 "name.homotypicalGroup.typifiedNames.taxonBases.$",
 387 "name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
 388 ----
 389
 390 *** /portal/taxon/\{taxon-uuid\}/accepted
 391
 392         Get the set of accepted Taxon entities for a given \{@link TaxonBase\} entity identified by the <code>\{taxon-uuid\}</code>.
 393
 394         <Returns:>
 395
 396         A set of Taxon entities which are initialized using the following initialization strategy:
 397
 398 ----
 399 "synonymRelations.$",
 400 "synonymRelations.synonym.$",
 401 "synonymRelations.synonym.name.taggedName",
 402 "synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
 403 "synonymRelations.synonym.name.nomenclaturalReference.inJournal",
 404 "synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
 405 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
 406 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
 407 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
 408 "synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
 409
 410 "name.homotypicalGroup.$",
 411 "name.homotypicalGroup.typifiedNames.$",
 412 "name.homotypicalGroup.typifiedNames.name.taggedName",
 413
 414 "name.homotypicalGroup.typifiedNames.taxonBases.$",
 415 "name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
 416 ----
 417
 418 ***  /portal/taxon/\{taxon-uuid\}/taxonRelationships
 419
 420         Get the list of TaxonRelationships for the given TaxonBase instance identified by the \{taxon-uuid\}.
 421
 422         <Returns:>
 423
 424         A list of TaxonRelationship entities which are initialized using the following initialization strategy:
 425
 426 ----
 427 "$",
 428 "type.inverseRepresentations",
 429 "fromTaxon.sec.authorTeam",
 430 "fromTaxon.name.taggedName"
 431 ----
 432
 433 *** /portal/taxon/\{taxon-uuid\}/nameRelationships
 434
 435         Get the list of NameRelationships of the Name associated with the TaxonBase instance identified by the \{taxon-uuid\}.
 436
 437         <Returns:>
 438
 439         A list of NameRelationship entities which are initialized using the following initialization strategy:
 440
 441 ----
 442 "$",
 443 "type.inverseRepresentations",
 444 "fromName.taggedName"
 445 ----
 446
 447 *** /portal/taxon/\{taxon-uuid\}/nameTypeDesignations
 448
 449         Get the list of TypeDesignationBases of the TaxonBase instance identified by the \{taxon-uuid\}.
 450
 451         <Returns:>
 452
 453         A list of TypeDesignationBase entities which are initialized using the following initialization strategy:
 454
 455 ----
 456 "typeSpecimen.$",
 457 "typeStatus.representations",
 458 "citation.authorTeam",
 459 "typeName.taggedName"
 460 ----
 461
 462 *** /portal/taxon/\{taxon-uuid\}/descriptions
 463
 464         Get the list of TaxonDescriptions of the Taxon instance identified by the \{taxon-uuid\}.
 465
 466         <Returns:>
 467
 468         A list of TaxonDescription entities which are initialized using the following initialization strategy:
 469
 470 ----
 471 "$",
 472 "elements.$",
 473 "elements.citation.authorTeam",
 474 "elements.multilanguageText",
 475 "elements.media.representations.parts"
 476 ----
 477
 478 *** /portal/taxon/\{taxon-uuid\}/media/\{mime type list\}/\{size\}[,[widthOrDuration\}][,\{height\}]/
 479
 480         Get the list of TaxonDescriptions of the Taxon instance identified by the \{taxon-uuid\}.
 481
 482         <Usage:>
 483
 484         /portal/taxon/\{taxon-uuid\}/media/\{mime type list\}/\{size\}[,[widthOrDuration\}][,\{height\}]/
 485
 486         <Whereas>
 487
 488         * <<\{mime type list\}>>: a comma separated list of mime types, in the order of preference. The forward slashes contained in the mime types must be replaced by a colon. Regular expressions can be used. Each media associated with this given taxon is being searched whereas the first matching mime type matching a representation always rules.
 489
 490         * <<\{size\}>>,<<\{widthOrDuration\}>>,<<\{height\}>>: (not jet implemented) valid values are an integer or the asterisk '*' as a wildcard
 491
 492         []
 493
 494         <Returns:>
 495
 496         A list of Media entities which are initialized using the following initialization strategy:
 497
 498 ----
 499 "$",
 500 "elements.$",
 501 "elements.citation.authorTeam",
 502 "elements.multilanguageText",
 503 "elements.media.representations.parts"
 504 ----
 505
 506 *** /portal/taxontree
 507
 508         Lists all available TaxonomicTrees.
 509
 510         <Returns:>
 511
 512         A list of TaxonomicTrees initialized by the following initialization strategy:
 513
 514 ----
 515 "reference.authorTeam.titleCache"
 516 ----
 517
 518 *** /portal/taxontree/\{tree-uuid\},\{rank-uuid\}
 519
 520         Lists all TaxonNodes of the specified TaxonomicTree for a given Rank. If a branch does not contain a TaxonNode with a TaxonName at the given Rank the node associated with the next lower Rank is taken as root node. If the rank is null the absolute root nodes will be returned.
 521
 522         <URI elements>:
 523
 524         * <\{tree-uuid\}> identifies the TaxonomicTree by its UUID.
 525
 526         * <\{rank-uuid\}> identifies the Rank by its UUID. May be left out.
 527
 528         []
 529
 530         <Returns:>
 531
 532         A list of TaxonNode entities initialized by the following initialization strategy:
 533
 534 ----
 535 "taxon.sec",
 536 "taxon.name.taggedName"
 537 ----
 538
 539 ***  /portal/taxontree/\{tree-uuid\},\{rank- uuid\}/\{taxon-uuid\}
 540
 541         Lists all child-TaxonNodes of the specified Taxon in the TaxonomicTree. The a given Rank is ignored in this method but for consistency reasons it has been allowed to included it into the URI.
 542
 543         <URI elements>:
 544
 545         * <\{tree-uuid\}> identifies the TaxonomicTree by its UUID.
 546
 547         * <\{rank-uuid\}> identifies the Rank by its UUID. May be left out.
 548
 549         * <\{taxon-uuid\}> identifies the Taxon by its UUID. - <required>.
 550
 551         []
 552
 553         <Returns:>
 554
 555         A list of TaxonNode entities initialized by the following initialization strategy:
 556
 557 ----
 558 "taxon.sec",
 559 "taxon.name.taggedName"
 560 ----
 561
 562 ***  /portal/taxontree/\{tree-uuid\},\{rank-uuid\}/\{taxon-uuid\}/path
 563
 564         Provides path of TaxonNodes from the base node to the node of the specified taxon.
 565
 566         <URI elements>:
 567
 568         * <\{tree-uuid\}> identifies the TaxonomicTree by its UUID.
 569
 570         * <\{rank-uuid\}> identifies the Rank by its UUID. May be left out.
 571
 572         * <\{taxon-uuid\}> identifies the Taxon by its UUID. - <required>.
 573
 574         []
 575
 576         <Returns:>
 577
 578         A list of TaxonNode entities initialized by the following initialization strategy:
 579
 580 ----
 581 "taxon.sec",
 582 "taxon.name.taggedName"
 583 ----
 584
 585 ** External Service
 586
 587 *** /geo/map/distribution/\{taxon-uuid\}
 588
 589         Assembles and returns URI parameter Strings for the EDIT Map Service.
 590 The distribution areas for the Taxon instance identified by the \{taxon-uuid\} are found and are translated into an valid URI parameter String.
 591 Higher level distribiution areas are expanded in order to include all nested sub-areas.