Project

General

Profile

CdmRestServices2 » History » Version 43

Andreas Kohlbecker, 07/22/2009 01:06 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 43 Andreas Kohlbecker
#### /{datasource-name}/name/{name-uuid}/typeDesignations
258
259
260
Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the {name-uuid}. 
261
262
263
 _Returns:_
264
265
266
a List of TypeDesignationBase entities which are initialized using the following initialization strategy: 
267
268
269
~~~
270
"$",
271
"citation.authorTeam",
272
"typifiedNames.taggedName"
273
~~~
274
275
276 42 Andreas Kohlbecker
#### /{datasource-name}/taxon/{taxon-uuid}/accepted
277
278
279
Get the set of accepted Taxon entities for a given {@link TaxonBase} entity identified by the <code>{taxon-uuid}</code>.
280
281
282
 _Returns:_
283
284 1 Andreas Kohlbecker
285 43 Andreas Kohlbecker
a set of Taxon entities which are initialized using the _default initialisation strategy_..
286 42 Andreas Kohlbecker
287
288
289 25 Andreas Kohlbecker
### Portal Service
290 28 Andreas Kohlbecker
291
292
293 35 Andreas Kohlbecker
#### /{datasource-name}/portal/name/{name-uuid}
294 28 Andreas Kohlbecker
295 35 Andreas Kohlbecker
296
The TaxonNameBase instance identified by the {name-uuid}. 
297
298
The returned TaxonNameBase is initialized by the following strategy 
299
300
301
~~~
302
~~~
303
304
305
#### /{datasource-name}/portal/name/{name-uuid}/descriptions
306
307
308
Get the list of TaxonNameDescriptions of the Name associated with the TaxonNameBase instance identified by the {name-uuid}.
309
310
311
_Returns:_
312
313
314
a List of TaxonNameDescription entities which are initialized using the following initialization strategy:
315
316
317
~~~
318
"uuid",
319
"feature",
320
"elements.$",
321
"elements.multilanguageText",
322
"elements.media.representations.parts"
323
~~~
324
325
326
#### /{datasource-name}/portal/name/{name-uuid}/typeDesignations
327
328
329
Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the {name-uuid}. 
330
331
332
_Returns:_
333
334
335
a List of TypeDesignationBase entities which are initialized using the following initialization strategy:
336
337
338
~~~
339
"citation.authorTeam",
340
"typeName.$",
341
"typeName.taggedName",
342
"typeStatus.representations",
343
"typeSpecimen.media.representations.parts"
344
~~~
345
346
347
348
#### /{datasource-name}/portal/taxon/{taxon-uuid}
349
350
351
Get the TaxonBase instance identified by the {taxon-uuid}. 
352
353
The returned Taxon is initialized by the following strategy TAXON_INIT_STRATEGY 
354
355
 
356
~~~
357
"*",
358
"relationsToThisName.fromTaxon.name.taggedName",
359
"name.$",
360
"name.taggedName",
361
"name.rank.representations",
362
"name.status.type.representations",
363
"descriptions.elements.$",
364
"descriptions.elements.area",
365
"descriptions.elements.area.$",
366
"descriptions.elements.multilanguageText",
367
"descriptions.elements.media.representations.parts",
368
~~~
369
370
371 28 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/find
372
373
374
Find Taxa, Synonyms, Common Names by name, either globally or in a specific geographic area. 
375
376
377 29 Andreas Kohlbecker
_URI Parameters:_
378 1 Andreas Kohlbecker
379 29 Andreas Kohlbecker
380 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_
381 28 Andreas Kohlbecker
382 33 Andreas Kohlbecker
* **treeUuid** the UUID of a TaxonomicTree to which the search is to be restricted. - _optional parameter_
383 28 Andreas Kohlbecker
384 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_
385 28 Andreas Kohlbecker
386 33 Andreas Kohlbecker
* **page** the number of the page to be returned, the first page has the pageNumber = 1 - _optional parameter_
387 28 Andreas Kohlbecker
388 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_
389 28 Andreas Kohlbecker
390 33 Andreas Kohlbecker
* **doTaxa** weather to search for instances of Taxon - _optional parameter_
391 28 Andreas Kohlbecker
392 33 Andreas Kohlbecker
* **doSynonyms** weather to search for instances of Synonym - _optional parameter_
393 28 Andreas Kohlbecker
394 33 Andreas Kohlbecker
* **doTaxaByCommonNames** for instances of Taxon by a common name used - _optional parameter_
395 28 Andreas Kohlbecker
396
 
397
_Returns:_
398
399
400
a pager on a list of IdentifiableEntitys initialized by the following strategy:
401
402
403
~~~
404
"*",
405
"relationsToThisName.fromTaxon.name.taggedName",
406
"name.$",
407
"name.taggedName",
408
"name.rank.representations",
409
"name.status.type.representations"
410
~~~
411 25 Andreas Kohlbecker
412
413 31 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/synonymy
414
415
416
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 
417
418
419
_Returns:_
420
421
422
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:
423
424
425
~~~
426 32 Andreas Kohlbecker
"synonymRelations.$",
427
"synonymRelations.synonym.$",
428
"synonymRelations.synonym.name.taggedName",
429
"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
430
"synonymRelations.synonym.name.nomenclaturalReference.inJournal",
431
"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
432
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
433
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
434
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
435
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
436
437
"name.homotypicalGroup.$",
438
"name.homotypicalGroup.typifiedNames.$",
439
"name.homotypicalGroup.typifiedNames.name.taggedName",
440
441
"name.homotypicalGroup.typifiedNames.taxonBases.$",
442
"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
443
~~~
444
445 1 Andreas Kohlbecker
446 32 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/accepted
447
448 1 Andreas Kohlbecker
449 42 Andreas Kohlbecker
Get the set of accepted Taxon entities for a given {@link TaxonBase} entity identified by the <code>{taxon-uuid}</code>.
450 32 Andreas Kohlbecker
451
452
 _Returns:_
453
454
455 42 Andreas Kohlbecker
a Set of Taxon entities which are initialized using the following initialization strategy:
456 32 Andreas Kohlbecker
457
458
~~~
459
"synonymRelations.$",
460
"synonymRelations.synonym.$",
461
"synonymRelations.synonym.name.taggedName",
462
"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",
463
"synonymRelations.synonym.name.nomenclaturalReference.inJournal",
464
"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",
465
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",
466
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",
467
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",
468
"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",
469
470
"name.homotypicalGroup.$",
471
"name.homotypicalGroup.typifiedNames.$",
472
"name.homotypicalGroup.typifiedNames.name.taggedName",
473
474
"name.homotypicalGroup.typifiedNames.taxonBases.$",
475
"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"
476
~~~
477
478
479
####  /{datasource-name}/portal/taxon/{taxon-uuid}/taxonRelationships
480
481
482
Get the list of TaxonRelationships for the given TaxonBase instance identified by the {taxon-uuid}. 
483
484
485
_Returns:_
486
487
488
a List of TaxonRelationship entities which are initialized using the following initialization strategy:
489
490
491
~~~
492
"$",
493
"type.inverseRepresentations",
494
"fromTaxon.sec.authorTeam",
495
"fromTaxon.name.taggedName"
496
~~~
497
498
499
#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameRelationships
500
501
502
Get the list of NameRelationships of the Name associated with the TaxonBase instance identified by the {taxon-uuid}. 
503
504
505
_Returns:_
506
507
508
a List of NameRelationship entities which are initialized using the following initialization strategy:
509
510
511
~~~
512
"$",
513
"type.inverseRepresentations",
514
"fromName.taggedName"
515
~~~
516
517
518
#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameTypeDesignations
519
520
521
Get the list of TypeDesignationBases of the TaxonBase instance identified by the {taxon-uuid}. 
522
523
524
_Returns:_
525
526
527
a List of TypeDesignationBase entities which are initialized using the following initialization strategy:
528
529
:
530
531
532
~~~
533
"typeSpecimen.$",
534
"typeStatus.representations",
535
"citation.authorTeam",
536
"typeName.taggedName"
537
~~~
538
539 1 Andreas Kohlbecker
540 32 Andreas Kohlbecker
#### /{datasource-name}/portal/taxon/{taxon-uuid}/descriptions
541
542
543
Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 
544
545
546 1 Andreas Kohlbecker
_Returns:_
547 32 Andreas Kohlbecker
548
549
a List of TaxonDescription entities which are initialized using the following initialization strategy:
550
551
552
~~~
553
"$",
554
"elements.$",
555
"elements.citation.authorTeam",
556
"elements.multilanguageText",
557
"elements.media.representations.parts"
558
~~~
559
560
561 35 Andreas Kohlbecker
#### /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 
562 32 Andreas Kohlbecker
563
564
Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 
565
566
567
_Usage:_
568
569 35 Andreas Kohlbecker
 /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 
570 32 Andreas Kohlbecker
571
 
572
_Whereas_ 
573
574
* *{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. 
575
576
* *{size}*,*{widthOrDuration}*,*{height}*: (not jet implemented) valid values are an integer or the asterisk '*' as a wildcard 
577
578
579
_Returns:_
580
581
582
a List of Media entities which are initialized using the following initialization strategy:
583
584
585
~~~
586
"$",
587
"elements.$",
588
"elements.citation.authorTeam",
589
"elements.multilanguageText",
590
"elements.media.representations.parts"
591 31 Andreas Kohlbecker
~~~
592
593 25 Andreas Kohlbecker
594
### Portal Taxonomy Service
595
596 1 Andreas Kohlbecker
597
598 41 Andreas Kohlbecker
#### /{datasource-name}/taxontree
599
600
601
Lists all available TaxonomicTrees. 
602
603
604
_Returns:_
605
606
607
A list of TaxonomicTrees initialized by the following initialization strategy:
608
609
610
~~~
611
"reference.authorTeam.titleCache"
612
~~~
613
614
615
#### /{datasource-name}/taxontree/{tree-uuid},{rank-uuid}
616
617
618
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. 
619
620
621
_URI elements_: 
622
623
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
624
625
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
626
627
628
_Returns:_
629
630
631
A List of TaxonNode entities initialized by the following initialization strategy:
632
633
634
~~~
635
"taxon.sec", 
636
"taxon.name.taggedName"
637
~~~
638
639
640
####  /{datasource-name}/taxontree/{tree-uuid},{rank- uuid}/{taxon-uuid}
641
642
643
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. 
644
645
646
_URI elements_: 
647
648
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
649
650
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
651
652
* _{taxon-uuid}_ identifies the Taxon by its UUID. - _required_. 
653
654
655
_Returns:_
656
657
658
A List of TaxonNode entities initialized by the following initialization strategy:
659
660
661
~~~
662
"taxon.sec", 
663
"taxon.name.taggedName"
664
~~~
665
666
667
####  {datasource-name}/taxontree/{tree-uuid},{rank-uuid}/{taxon-uuid}/path
668
669
670
Provides path of TaxonNodes from the base node to the node of the specified taxon. 
671
672
673
_URI elements_: 
674
675
* _{tree-uuid}_ identifies the TaxonomicTree by its UUID. 
676
677
* _{rank-uuid}_ identifies the Rank by its UUID. May be left out. 
678
679
* _{taxon-uuid}_ identifies the Taxon by its UUID. - _required_. 
680
681
682
_Returns:_
683
684
685
A List of TaxonNode entities initialized by the following initialization strategy:
686
687
688
~~~
689
"taxon.sec", 
690
"taxon.name.taggedName"
691
~~~
692
693
694 1 Andreas Kohlbecker
### External Service
695 41 Andreas Kohlbecker
696
697
698
#### /{datasource-name}/geo/map/distribution/{taxon-uuid}
699
700
701
Assembles and returns URI parameter Strings for the EDIT Map Service. 
702
703
The distribution areas for the Taxon instance identified by the {taxon-uuid} are found and are translated into an valid URI parameter String. 
704
705
Higher level distribiution areas are expanded in order to include all nested sub-areas.