From 9e916eb21fa9204466733a4390b80147464a7c0a Mon Sep 17 00:00:00 2001 From: Cherian Mathew Date: Wed, 1 Aug 2012 08:28:40 +0000 Subject: [PATCH] added subdirectory for cdmlib remote endpoint documentation added apt files for the name catalogue web service documentation --- .gitattributes | 3 + .../apt/remote/name-catalogue-default.apt | 69 +++++++++++++++ .../apt/remote/name-catalogue-name-info.apt | 64 ++++++++++++++ .../apt/remote/name-catalogue-taxon-info.apt | 83 +++++++++++++++++++ 4 files changed, 219 insertions(+) create mode 100755 src/site/apt/remote/name-catalogue-default.apt create mode 100755 src/site/apt/remote/name-catalogue-name-info.apt create mode 100755 src/site/apt/remote/name-catalogue-taxon-info.apt diff --git a/.gitattributes b/.gitattributes index 085c740f43..e4aff7ba5a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2078,6 +2078,9 @@ src/site/apt/index.apt -text src/site/apt/oai-pmh.apt -text src/site/apt/overview.apt -text src/site/apt/reference.apt -text +src/site/apt/remote/name-catalogue-default.apt -text +src/site/apt/remote/name-catalogue-name-info.apt -text +src/site/apt/remote/name-catalogue-taxon-info.apt -text src/site/apt/rest-api.apt -text src/site/fml/faq.fml -text src/site/fml/troubleshooting.fml -text diff --git a/src/site/apt/remote/name-catalogue-default.apt b/src/site/apt/remote/name-catalogue-default.apt new file mode 100755 index 0000000000..0a57e3c3b2 --- /dev/null +++ b/src/site/apt/remote/name-catalogue-default.apt @@ -0,0 +1,69 @@ + + +CDM Taxonomic Name Search API + + This web service endpoint serves as a search engine for scientific name-related taxonomic information. + + The request parameters are : + + * '<>' [mandatory] : this could either be the base scientific name or the complete scientific name. + + * '<>' [optional, default value = <<>>] : this parameter could have the values, + + * <<>> : to be used in the case of scientific names without authorship strings other other markers (e.g. Abies Alba). + + * <<>> : to be used in the case of scientific names with authorship strings other other markers (e.g. Abies alba Mill.). + + [] + + The response format can be set by appending the format extension to the service endpoint. Currently this web service supports JSON (fully implemented) and XML (partially implemented). + + The response returned by this web service endpoint is described as, + + * <<<request>>> + + * <<<query>>> : scientific name provided as input. + + * <<<response>>> + + * <<<name>>> : base scientific name. + + * <<<title>>> : complete scientific name. + + * <<<taxonConceptUuids>>> : list of uuids of all taxa corresponding to this name. + + * <<<acceptedTaxonUuids>>> : list of uuids of all accepted taxa related to the taxa corresponding to the taxonConceptUuids list. + + + Features: + + * Possibility to perform multiple queries in one single web service call. + + * Standardised and structured error messages. + + Examples : + + * Base scientific name search : + + * {{{./name_catalogue.json?query=Abies Alba} /{datasource-name}/name_catalogue.json?query=Abies Alba}} + + * Complete scientific name search : + + * {{{./name_catalogue.json?query=Abies Alba Mill.&type=title} /{datasource-name}/name_catalogue.json?query=Abies Alba Mill.&type=title}} + + * Multiple queries : + + * {{{./name_catalogue.json?query=Abies Alba&query=Manihot esculenta} /{datasource-name}/name_catalogue.json?query=Abies Alba&query=Manihot esculenta}} + + * {{{./name_catalogue.json?query=Abies Alba Mill.&query=Manihot esculenta Crantz&type=title} /{datasource-name}/name_catalogue.json?query=Abies Alba Mill.&query=Manihot esculenta Crantz&type=title}} + + * Errors : + + * {{{./name_catalogue.json?query=Abies Alb} /{datasource-name}/name_catalogue.json?query=Abies Alb}} + + * {{{./name_catalogue.json?query=Abies Alba&query=Manihot escenta} /{datasource-name}/name_catalogue.json?query=Abies Alba&query=Manihot escenta}} + + + + + \ No newline at end of file diff --git a/src/site/apt/remote/name-catalogue-name-info.apt b/src/site/apt/remote/name-catalogue-name-info.apt new file mode 100755 index 0000000000..b10fe1c08a --- /dev/null +++ b/src/site/apt/remote/name-catalogue-name-info.apt @@ -0,0 +1,64 @@ + + +CDM Taxonomic Name Information API + + This web service endpoint provides information related a specific name uuid. + + The request parameters are : + + * '<<nameUuid>>' [mandatory] : uuid of the scientific name . + + + [] + + The response format can be set by appending the format extension to the service endpoint. Currently this web service supports JSON (fully implemented) and XML (partially implemented). + + The response returned by this web service endpoint is described as, + + * <<<request>>> + + * <<<nameUuid>>> : scientific name uuid provided as input. + + * <<<response>>> + + * <<<name>>> : base scientific name of requested name uuid. + + * <<<title>>> : complete scientific name. + + * <<<citation>>> : citation related to requested name uuid. + + * <<<nameRelationships>>> : list of relationships that the name corresponding to the requested name uuid has with other names. + + * <<<nomenclatureStatus>>> : list of nomenclature status related to the name corresponding to the requested name uuid. + + * <<<rank>>> : rank of name corresponding to the requested name uuid. + + * <<<taxonLsids>>> : list of lsids of taxa related to the name corresponding to the requested name uuid. + + * <<<taxonUuids>>> : list of uuids of taxa related to the name corresponding to the requested name uuid. + + + Features: + + * Possibility to perform multiple queries in one single web service call. + + * Standardised and structured error messages. + + Examples : + + * Single name uuid request : + + * {{{../name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02-4301fd78debf} /{datasource-name}/name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02-4301fd78debf}} + + * Multiple name uuid request : + + * {{{../name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02-4301fd78debf&nameUuid=0d5e07b6-2646-4210-80e0-fcd449e26b57} /{datasource-name}/name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02-4301fd78debf&nameUuid=0d5e07b6-2646-4210-80e0-fcd449e26b57}} + + * Errors : + + * {{{../name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02} /{datasource-name}/name_catalogue/name.json?nameUuid=cd4bc51f-ddcd-4e9c-aa02}} + + + + + \ No newline at end of file diff --git a/src/site/apt/remote/name-catalogue-taxon-info.apt b/src/site/apt/remote/name-catalogue-taxon-info.apt new file mode 100755 index 0000000000..256c6867f9 --- /dev/null +++ b/src/site/apt/remote/name-catalogue-taxon-info.apt @@ -0,0 +1,83 @@ + + +CDM Taxonomic Taxon Information API + + This web service endpoint provides information related a specific taxon uuid. + + The request parameters are : + + * '<<taxonUuid>>' [mandatory] : uuid of the scientific name. + + * '<<classification>>' [optional, default value = <<<default>>>] : this parameter could have the values, + + * <<<<any of the classification keys present in the database>>>> : to be used to retrieve the corresponding classification. + + * <<<default>>> : to be used to retrieve the first in the alphabetically sorted list of classifications available in the database (currently this is 'CatalogueOfLife'). + + * <<<default>>> : to be used to retrieve all classifications as a ('key','classification') map. + + + [] + + The response format can be set by appending the format extension to the service endpoint. Currently this web service supports JSON (fully implemented) and XML (partially implemented). + + The response returned by this web service endpoint is described as, + + * <<<request>>> + + * <<<taxonUuid>>> : taxon uuid provided as input. + + * <<<response>>> + + * <<<taxon>>> : taxon information corresponding to the requested taxon uuid, which includes, + + * <<<title>>> : complete scientific name of taxon. + + * <<<taxonStatus>>> : taxonomic status of taxon. + + * <<<flags>>> : list of flags related to the taxon and their values. + + * <<<classification>>> : classification of the requested taxon. + + * <<<relatedTaxa>>> : list of taxa related to the requested taxon, each of which has the following elements, + + * <<<title>>> : complete scientific name of related taxon. + + * <<<taxonUuid>>> : uuid of related taxon. + + * <<<taxonStatus>>> : taxonomic status of related taxon. + + * <<<sourceUrl>>> : stable url which represents the related taxon. + + * <<<relationshipType>>> : type of relationship the requested taxon has with the related taxa. + + + Features: + + * Possibility to perform multiple queries in one single web service call. + + * Standardised and structured error messages. + + Examples : + + * Single taxon uuid request : + + * {{{../name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9} /{datasource-name}/name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9}} + + * Single taxon uuid request with all possible classifications : + + * {{{../name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9&classification=all} /{datasource-name}/name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9&classification=all}} + + + * Multiple taxon uuid request : + + * {{{../name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9&taxonUuid=1e331521-8db2-4da0-926a-fe7e0425ae03} /{datasource-name}/name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751d9&taxonUuid=1e331521-8db2-4da0-926a-fe7e0425ae03}} + + * Errors : + + * {{{../name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751} /{datasource-name}/name_catalogue/taxon.json?taxonUuid=6d2a61d0-3167-4f19-840a-4280dc3751}} + + + + + \ No newline at end of file -- 2.34.1