Project

General

Profile

CdmRestServices2 » History » Version 45

Andreas Kohlbecker, 07/22/2009 01:12 PM

1 1 Andreas Kohlbecker
{{>toc}}
2
3
4
5 41 Andreas Kohlbecker
_Developers implementation notes are found in [[CdmRestServicesImplementationNotes]]._
6 1 Andreas Kohlbecker
7
8 36 Andreas Kohlbecker
9
----
10
11
12
13 2 Andreas Kohlbecker
# CDM REST Services 2.0
14 1 Andreas Kohlbecker
15
16 4 Andreas Kohlbecker
The CDM REST Services are a web based interface to resources stored in a [[CommunityServer|CDM Community Server]]. 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, write operations will be available in the near future.
17 1 Andreas Kohlbecker
18 3 Andreas Kohlbecker
19 16 Andreas Kohlbecker
In contrast to the former [[CdmRestServices1|CDM REST Services 1.0]] the new architecture directly exposes domain model entities. Whereas the version 1.0 still was build using the  [DTO/Assembler pattern](http://java.sun.com/blueprints/corej2eepatterns/Patterns/TransferObject.html)  the new implementation provides direct serializations of the objects as they are stored in the CDM where ever possible. For the external representations, like LSIDs and TDWG data exchange schema like TCS however using DTOs is unavoidable. Now for the **API Service** there is no longer a difference between the data model used to store and manage CDM objects and another one used to transfer them to web based clients. Thereby it has become much easier to use the web service. The same account also for the **Portal Service** except that this service adds some fields like localized representations and to the pure CDM entities.
20 3 Andreas Kohlbecker
21 1 Andreas Kohlbecker
22
23 16 Andreas Kohlbecker
## Service Sections
24 1 Andreas Kohlbecker
25 16 Andreas Kohlbecker
26
The CDM REST Services architecture is functionally separated into tree different parts:
27
28
29 18 Andreas Kohlbecker
* 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.
30 16 Andreas Kohlbecker
31 18 Andreas Kohlbecker
* 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. 
32 1 Andreas Kohlbecker
33 18 Andreas Kohlbecker
* The **Portal Taxonomy Service** delivering the taxonomic classification tree.
34 16 Andreas Kohlbecker
35 19 Andreas Kohlbecker
* The **External Service** services supporting non CDM applications and services like for example a map generation service, LSID Services.
36 18 Andreas Kohlbecker
37 16 Andreas Kohlbecker
 
38 17 Andreas Kohlbecker
Detailed descriptions of the services are available [[CdmRestServices2#ServiceDescriptions|below]].
39 16 Andreas Kohlbecker
40
41
42 1 Andreas Kohlbecker
## Object Boundaries
43 14 Andreas Kohlbecker
44 1 Andreas Kohlbecker
45 16 Andreas Kohlbecker
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.
46 1 Andreas Kohlbecker
47
48 27 Andreas Kohlbecker
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. 
49 14 Andreas Kohlbecker
50 18 Andreas Kohlbecker
51 1 Andreas Kohlbecker
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 to about ten levels for specific branches.
52 19 Andreas Kohlbecker
53
54 26 Andreas Kohlbecker
The extend of objects, i.e the initialization depth of CDM entities is documented in the [[CdmRestServices2#ServiceDescriptions|ServiceDescriptions]] 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. 
55 16 Andreas Kohlbecker
56 1 Andreas Kohlbecker
57 20 Andreas Kohlbecker
* 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().
58 1 Andreas Kohlbecker
59 20 Andreas Kohlbecker
* 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.
60 1 Andreas Kohlbecker
61 20 Andreas Kohlbecker
* 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
62
63 22 Andreas Kohlbecker
* *toOne-Wildcard ($) This wildcard is used to select all property getters which reference to one associated bean. A wildcard subsequently terminates a 'property path'.
64 20 Andreas Kohlbecker
65 22 Andreas Kohlbecker
* *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'.
66 1 Andreas Kohlbecker
67 23 Andreas Kohlbecker
* Combined (name1.name2[index].$) - Combining mapped, nested, and indexed and wildcard references is also supported.
68
69 1 Andreas Kohlbecker
	
70 26 Andreas Kohlbecker
~This syntax description partially is lend from  [Apache Commons BeanUtils](http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/org/apache/commons/beanutils/PropertyUtilsBean.html) ~
71
72
73 27 Andreas Kohlbecker
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 source:"trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java".
74 26 Andreas Kohlbecker
75 1 Andreas Kohlbecker
76
77 24 Andreas Kohlbecker
*Developer Hints*:
78 20 Andreas Kohlbecker
79 22 Andreas Kohlbecker
80 24 Andreas Kohlbecker
The initialization od CDM entities is performed by implementations of the  source:"trunk/cdmlib/cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/BeanInitializer.java" Interface.
81 20 Andreas Kohlbecker
82
83
84
85 6 Andreas Kohlbecker
## Content Negotiation
86
87
88
There are two ways to demand a special content type:
89
90
91
1. by file extension (*.json or *.xml)
92
93 9 Andreas Kohlbecker
1. by  [Accept HTTP request header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) #sec14.1 - Accepted mime types are: `application/json@, @text/xml`    
94 6 Andreas Kohlbecker
95
1. Default: XML
96
97
98 12 Andreas Kohlbecker
The [[CdmRestServices2|CDM REST Services 2.0]] 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. 
99 6 Andreas Kohlbecker
100
101 1 Andreas Kohlbecker
 **Developer Hints** 
102 7 Andreas Kohlbecker
103
104
Classes involved in Content Negotiation:
105
106 6 Andreas Kohlbecker
107 11 Andreas Kohlbecker
* source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/controller/interceptor/ContentNegociationHandlerInterceptor.java"
108 8 Andreas Kohlbecker
109 9 Andreas Kohlbecker
Configuration in: 
110 8 Andreas Kohlbecker
111 6 Andreas Kohlbecker
* source:"trunk/cdmlib/cdmlib-remote/src/main/webapp/WEB-INF/cdmrest-servlet.xml#L24"
112
113
114 1 Andreas Kohlbecker
115
## Localization
116
117 12 Andreas Kohlbecker
118 20 Andreas Kohlbecker
I order to provide the client with localized resources some services respect the  [Accept-Language HTTP header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) #sec14.4.
119 12 Andreas Kohlbecker
120
For example the Portal service returns localized representations according to the Language tags supplied in the  Accept-Language HTTP header. For each single CDM entity having language dependent representation (see:  source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/model/common/Representation.java" or source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/model/common/MultilanguageText.java")
121
122 11 Andreas Kohlbecker
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 source:"trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/common/Language.java#L126" and if necessary further falls back to return the first representation found if any exists.
123 1 Andreas Kohlbecker
124
125 12 Andreas Kohlbecker
Please see below for detailed information on how and whether localization is handled by the different service sections.
126
127
128 11 Andreas Kohlbecker
129 9 Andreas Kohlbecker
 **Developer Hints** 
130
131
132 6 Andreas Kohlbecker
133
Classes involved in Content Negotiation:
134
135
136
* source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/controller/interceptor/LocaleContextHandlerInterceptor.java"
137 5 Andreas Kohlbecker
138 3 Andreas Kohlbecker
Configuration in: 
139 1 Andreas Kohlbecker
140
* -- not necessary --
141
142
143 10 Andreas Kohlbecker
144 1 Andreas Kohlbecker
145 14 Andreas Kohlbecker
## Character Encoding
146 1 Andreas Kohlbecker
147 14 Andreas Kohlbecker
148 10 Andreas Kohlbecker
All data is returned in UTF-8 character encoding.
149 14 Andreas Kohlbecker
150 10 Andreas Kohlbecker
151 16 Andreas Kohlbecker
152 1 Andreas Kohlbecker
## Service Descriptions
153
154
155 36 Andreas Kohlbecker
The syntax of the mapped service URIs contains the the {datasource-name} path element. The available {datasource-name}s are defined in a configuration file which is loaded by the UpdatableRoutingDataSource. By default the "datasources.xml" in @ {USER_HOME}./cdmLibrary @ is being used (for details please refer to [[WebserviceDeployment]]). If the UpdatableRoutingDataSource is not being used in the actual application context, any arbitrary {datasource-name} may be used.
156 28 Andreas Kohlbecker
157
158 25 Andreas Kohlbecker
159 1 Andreas Kohlbecker
### API Service
160
161
162 36 Andreas Kohlbecker
The are a clean RESTful webservice, which will expose data in a modular, normalized way. 
163 1 Andreas Kohlbecker
164 36 Andreas Kohlbecker
It is a more-or-less one-to-one concordance between URIs and service api methods. 
165 1 Andreas Kohlbecker
166 36 Andreas Kohlbecker
Due to its generic architecture the URIs are also generic and follow a common pattern which is repeated in each controller. 
167 1 Andreas Kohlbecker
168 39 Andreas Kohlbecker
In the following the generic URIs are documented first followed by type specific implementations. The pathelement {base-type} is frequently used in generid URIs.
169 1 Andreas Kohlbecker
170
171 38 Andreas Kohlbecker
_Valid Values for {base-type} are_:
172
173
174 36 Andreas Kohlbecker
* *agent*: Service URIs returning AgentBase or sub type entities.
175 1 Andreas Kohlbecker
176 36 Andreas Kohlbecker
* *description*: Service URIs returning DescriptionBase or sub type entities. 
177 1 Andreas Kohlbecker
178 36 Andreas Kohlbecker
* *feature*: Service URIs returning DescriptionBase or sub type entities
179 1 Andreas Kohlbecker
180 36 Andreas Kohlbecker
* *media*: Service URIs returning Media or sub type entities
181 1 Andreas Kohlbecker
182 36 Andreas Kohlbecker
* *name*: Service URIs returning TaxonNameBase or sub type entities
183 1 Andreas Kohlbecker
184 36 Andreas Kohlbecker
* *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
Most services are using the **default initialisation strategy** which is:
194
195
~~~
196
"$"
197
~~~
198
199
200
#### /{datasource-name}/{base-type}/
201
202
203
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}. 
204
205 40 Andreas Kohlbecker
The returned {base-type} instances are initialized by the _default initialisation strategy_. 
206 1 Andreas Kohlbecker
207 37 Andreas Kohlbecker
208 38 Andreas Kohlbecker
_URI Parameters to return a Pager_:
209 36 Andreas Kohlbecker
210 38 Andreas Kohlbecker
211 37 Andreas Kohlbecker
* _pageNumber_ the number of the page to be returned, the first page has the pageNumber = 1 - _optional parameter_ 
212
213 36 Andreas Kohlbecker
* _pageSize_ the maximum number of entities returned per page (can be null to return all entities in a single page) - _optional parameter_ 
214 37 Andreas Kohlbecker
215 40 Andreas Kohlbecker
* _type_  Further restricts the type of entities to be returned. If null the type mapped by {base-type} is being used. - _optional parameter_ 
216 36 Andreas Kohlbecker
217
218 38 Andreas Kohlbecker
_URI Parameters to return a List_:
219 36 Andreas Kohlbecker
220
221 41 Andreas Kohlbecker
* _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! ** 
222 36 Andreas Kohlbecker
223 37 Andreas Kohlbecker
* _limit_ The maximum number of entities returned. - _optional parameter_ 
224 36 Andreas Kohlbecker
225 40 Andreas Kohlbecker
* _type_ Further restricts the type of entities to return. If null the type mapped by {base-type} is being used. - _optional parameter_ 
226 36 Andreas Kohlbecker
227
228
229
#### /{datasource-name}/{base-type}/name/{uuid}
230
231
232
Get the {base-type} entity identified by the {uuid}. 
233
234
235
_Returns:_
236
237
238 40 Andreas Kohlbecker
The returned {base-type} entity is initialized by the _default initialisation strategy_. 
239 36 Andreas Kohlbecker
240
241
242
####  /{datasource-name}/{base-type}/name/{uuid}/annotation
243
244
245
Get the a Pager on the Annotations for the {base-type} entity identified by the {uuid}. 
246
247
248
_Returns:_
249
250
251
Pager on the Annotations for the {base-type} entity identified by the {uuid}. 
252
253 40 Andreas Kohlbecker
The returned {base-type} entity are initialized by the _default initialisation strategy_. 
254 1 Andreas Kohlbecker
255
256
257 44 Andreas Kohlbecker
----
258
259
260
261 43 Andreas Kohlbecker
#### /{datasource-name}/name/{name-uuid}/typeDesignations
262
263
264
Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the {name-uuid}. 
265
266
267
 _Returns:_
268
269
270
a List of TypeDesignationBase entities which are initialized using the following initialization strategy: 
271
272
273
~~~
274
"$",
275
"citation.authorTeam",
276
"typifiedNames.taggedName"
277
~~~
278
279
280 42 Andreas Kohlbecker
#### /{datasource-name}/taxon/{taxon-uuid}/accepted
281
282
283
Get the set of accepted Taxon entities for a given {@link TaxonBase} entity identified by the <code>{taxon-uuid}</code>.
284
285
286
 _Returns:_
287
288 1 Andreas Kohlbecker
289 43 Andreas Kohlbecker
a set of Taxon entities which are initialized using the _default initialisation strategy_..
290 42 Andreas Kohlbecker
291
292
293 25 Andreas Kohlbecker
### Portal Service
294 28 Andreas Kohlbecker
295
296
297 35 Andreas Kohlbecker
#### /{datasource-name}/portal/name/{name-uuid}
298 28 Andreas Kohlbecker
299 35 Andreas Kohlbecker
300
The TaxonNameBase instance identified by the {name-uuid}. 
301
302
The returned TaxonNameBase is initialized by the following strategy 
303
304
305
~~~
306
~~~
307
308
309
#### /{datasource-name}/portal/name/{name-uuid}/descriptions
310
311
312
Get the list of TaxonNameDescriptions of the Name associated with the TaxonNameBase instance identified by the {name-uuid}.
313
314
315
_Returns:_
316
317
318
a List of TaxonNameDescription entities which are initialized using the following initialization strategy:
319
320
321
~~~
322
"uuid",
323
"feature",
324
"elements.$",
325
"elements.multilanguageText",
326
"elements.media.representations.parts"
327
~~~
328
329
330
#### /{datasource-name}/portal/name/{name-uuid}/typeDesignations
331
332
333
Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the {name-uuid}. 
334
335
336
_Returns:_
337
338
339
a List of TypeDesignationBase entities which are initialized using the following initialization strategy:
340
341
342
~~~
343
"citation.authorTeam",
344
"typeName.$",
345
"typeName.taggedName",
346
"typeStatus.representations",
347
"typeSpecimen.media.representations.parts"
348
~~~
349
350
351
352
#### /{datasource-name}/portal/taxon/{taxon-uuid}
353
354
355
Get the TaxonBase instance identified by the {taxon-uuid}. 
356
357
The returned Taxon is initialized by the following strategy TAXON_INIT_STRATEGY 
358
359
 
360
~~~
361
"*",
362
"relationsToThisName.fromTaxon.name.taggedName",
363
"name.$",
364
"name.taggedName",
365
"name.rank.representations",
366
"name.status.type.representations",
367
"descriptions.elements.$",
368
"descriptions.elements.area",
369
"descriptions.elements.area.$",
370
"descriptions.elements.multilanguageText",
371
"descriptions.elements.media.representations.parts",
372
~~~
373
374
375 28 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/find
376
377
378
Find Taxa, Synonyms, Common Names by name, either globally or in a specific geographic area. 
379
380
381 29 Andreas Kohlbecker
_URI Parameters:_
382 1 Andreas Kohlbecker
383 29 Andreas Kohlbecker
384 33 Andreas Kohlbecker
* **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_
385 28 Andreas Kohlbecker
386 33 Andreas Kohlbecker
* **treeUuid** the UUID of a TaxonomicTree to which the search is to be restricted. - _optional parameter_
387 28 Andreas Kohlbecker
388 33 Andreas Kohlbecker
* **areas** restrict the search to a set of geographic NamedAreas. The parameter currently takes a list of TDWG area labels.  - _optional parameter_
389 28 Andreas Kohlbecker
390 33 Andreas Kohlbecker
* **page** the number of the page to be returned, the first page has the pageNumber = 1 - _optional parameter_
391 28 Andreas Kohlbecker
392 33 Andreas Kohlbecker
* **pageSize** the maximum number of entities returned per page (can be null to return all entities in a single page) - _optional parameter_
393 28 Andreas Kohlbecker
394 33 Andreas Kohlbecker
* **doTaxa** weather to search for instances of Taxon - _optional parameter_
395 28 Andreas Kohlbecker
396 33 Andreas Kohlbecker
* **doSynonyms** weather to search for instances of Synonym - _optional parameter_
397 28 Andreas Kohlbecker
398 33 Andreas Kohlbecker
* **doTaxaByCommonNames** for instances of Taxon by a common name used - _optional parameter_
399 28 Andreas Kohlbecker
400
 
401
_Returns:_
402
403
404
a pager on a list of IdentifiableEntitys initialized by the following strategy:
405
406
407
~~~
408
"*",
409
"relationsToThisName.fromTaxon.name.taggedName",
410
"name.$",
411
"name.taggedName",
412
"name.rank.representations",
413
"name.status.type.representations"
414
~~~
415 25 Andreas Kohlbecker
416
417 31 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/synonymy
418
419
420
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 
421
422
423
_Returns:_
424
425
426
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:
427
428
429
~~~
430 32 Andreas Kohlbecker
"synonymRelations.$",
431
"synonymRelations.synonym.$",
432
"synonymRelations.synonym.name.taggedName",
433
"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
434
"synonymRelations.synonym.name.nomenclaturalReference.inJournal",
435
"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
436
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
437
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
438
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
439
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
440
441
"name.homotypicalGroup.$",
442
"name.homotypicalGroup.typifiedNames.$",
443
"name.homotypicalGroup.typifiedNames.name.taggedName",
444
445
"name.homotypicalGroup.typifiedNames.taxonBases.$",
446
"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
447
~~~
448
449 1 Andreas Kohlbecker
450 32 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/accepted
451
452 1 Andreas Kohlbecker
453 42 Andreas Kohlbecker
Get the set of accepted Taxon entities for a given {@link TaxonBase} entity identified by the <code>{taxon-uuid}</code>.
454 32 Andreas Kohlbecker
455
456
 _Returns:_
457
458
459 42 Andreas Kohlbecker
a Set of Taxon entities which are initialized using the following initialization strategy:
460 32 Andreas Kohlbecker
461
462
~~~
463
"synonymRelations.$",
464
"synonymRelations.synonym.$",
465
"synonymRelations.synonym.name.taggedName",
466
"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
467
"synonymRelations.synonym.name.nomenclaturalReference.inJournal",
468
"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
469
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
470
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
471
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
472
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
473
474
"name.homotypicalGroup.$",
475
"name.homotypicalGroup.typifiedNames.$",
476
"name.homotypicalGroup.typifiedNames.name.taggedName",
477
478
"name.homotypicalGroup.typifiedNames.taxonBases.$",
479
"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
480
~~~
481
482
483
####  /{datasource-name}/portal/taxon/{taxon-uuid}/taxonRelationships
484
485
486
Get the list of TaxonRelationships for the given TaxonBase instance identified by the {taxon-uuid}. 
487
488
489
_Returns:_
490
491
492
a List of TaxonRelationship entities which are initialized using the following initialization strategy:
493
494
495
~~~
496
"$",
497
"type.inverseRepresentations",
498
"fromTaxon.sec.authorTeam",
499
"fromTaxon.name.taggedName"
500
~~~
501
502
503
#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameRelationships
504
505
506
Get the list of NameRelationships of the Name associated with the TaxonBase instance identified by the {taxon-uuid}. 
507
508
509
_Returns:_
510
511
512
a List of NameRelationship entities which are initialized using the following initialization strategy:
513
514
515
~~~
516
"$",
517
"type.inverseRepresentations",
518
"fromName.taggedName"
519
~~~
520
521
522
#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameTypeDesignations
523
524
525
Get the list of TypeDesignationBases of the TaxonBase instance identified by the {taxon-uuid}. 
526
527
528
_Returns:_
529
530
531
a List of TypeDesignationBase entities which are initialized using the following initialization strategy:
532
533
:
534
535
536
~~~
537
"typeSpecimen.$",
538
"typeStatus.representations",
539
"citation.authorTeam",
540
"typeName.taggedName"
541
~~~
542
543 1 Andreas Kohlbecker
544 32 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/descriptions
545
546
547
Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 
548
549
550 1 Andreas Kohlbecker
_Returns:_
551 32 Andreas Kohlbecker
552
553
a List of TaxonDescription entities which are initialized using the following initialization strategy:
554
555
556
~~~
557
"$",
558
"elements.$",
559
"elements.citation.authorTeam",
560
"elements.multilanguageText",
561
"elements.media.representations.parts"
562
~~~
563
564
565 35 Andreas Kohlbecker
#### /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 
566 32 Andreas Kohlbecker
567
568
Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 
569
570
571
_Usage:_
572
573 35 Andreas Kohlbecker
 /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 
574 32 Andreas Kohlbecker
575
 
576
_Whereas_ 
577
578
* *{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. 
579
580
* *{size}*,*{widthOrDuration}*,*{height}*: (not jet implemented) valid values are an integer or the asterisk '*' as a wildcard 
581
582
583
_Returns:_
584
585
586
a List of Media entities which are initialized using the following initialization strategy:
587
588
589
~~~
590
"$",
591
"elements.$",
592
"elements.citation.authorTeam",
593
"elements.multilanguageText",
594
"elements.media.representations.parts"
595 31 Andreas Kohlbecker
~~~
596
597 25 Andreas Kohlbecker
598
### Portal Taxonomy Service
599
600 1 Andreas Kohlbecker
601
602 41 Andreas Kohlbecker
#### /{datasource-name}/taxontree
603
604
605
Lists all available TaxonomicTrees. 
606
607
608
_Returns:_
609
610
611
A list of TaxonomicTrees initialized by the following initialization strategy:
612
613
614
~~~
615
"reference.authorTeam.titleCache"
616
~~~
617
618
619
#### /{datasource-name}/taxontree/{tree-uuid},{rank-uuid}
620
621
622
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. 
623
624
625
_URI elements_: 
626
627
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
628
629
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
630
631
632
_Returns:_
633
634
635
A List of TaxonNode entities initialized by the following initialization strategy:
636
637
638
~~~
639
"taxon.sec", 
640
"taxon.name.taggedName"
641
~~~
642
643
644
####  /{datasource-name}/taxontree/{tree-uuid},{rank- uuid}/{taxon-uuid}
645
646
647
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. 
648
649
650
_URI elements_: 
651
652
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
653
654
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
655
656
* _{taxon-uuid}_ identifies the Taxon by its UUID. - _required_. 
657
658
659
_Returns:_
660
661
662
A List of TaxonNode entities initialized by the following initialization strategy:
663
664
665
~~~
666
"taxon.sec", 
667
"taxon.name.taggedName"
668
~~~
669
670
671 45 Andreas Kohlbecker
####  /{datasource-name}/taxontree/{tree-uuid},{rank-uuid}/{taxon-uuid}/path
672 41 Andreas Kohlbecker
673
674
Provides path of TaxonNodes from the base node to the node of the specified taxon. 
675
676
677
_URI elements_: 
678
679
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
680
681
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
682
683
* _{taxon-uuid}_ identifies the Taxon by its UUID. - _required_. 
684
685
686
_Returns:_
687
688
689
A List of TaxonNode entities initialized by the following initialization strategy:
690
691
692
~~~
693
"taxon.sec", 
694
"taxon.name.taggedName"
695
~~~
696
697
698 1 Andreas Kohlbecker
### External Service
699 41 Andreas Kohlbecker
700
701
702
#### /{datasource-name}/geo/map/distribution/{taxon-uuid}
703
704
705
Assembles and returns URI parameter Strings for the EDIT Map Service. 
706
707
The distribution areas for the Taxon instance identified by the {taxon-uuid} are found and are translated into an valid URI parameter String. 
708
709
Higher level distribiution areas are expanded in order to include all nested sub-areas.