moved common crop name out of URL

plantbreeding · Apr 18, 2018 · 7b2c951 · 7b2c951
1 parent 1477070
commit 7b2c951
Show file tree

Hide file tree

Showing 14 changed files with 423 additions and 27 deletions.
diff --git a/Scripts/buildBrapiBlueprint.sh b/Scripts/buildBrapiBlueprint.sh
@@ -18,7 +18,7 @@ touch $BRAPI_FILE
 # Tedious to write out the names of all the directories and files but this let's us control the order of assembly
 BRAPI_PREFIX=${BRAPI_DIR}/Specification/
 
-sources=("README.md" 
+sources=(  "GeneralInfo/Intro.md"
 	       "GeneralInfo/URL_Structure.md"
 	       "GeneralInfo/Response_Structure.md"
 	       "GeneralInfo/Error_Handling.md"
@@ -30,6 +30,9 @@ sources=("README.md"
 	       "Authentication/Authentication.md"
 	       "Calls/README.md" 
 	       "Calls/Calls.md" 
+	       "Crops/README.md"
+	       "Crops/CommonCropNames_GET.md"
+	       "Crops/ListCrops_Deprecated.md"
 	       "Germplasm/README.md"
 	       "Germplasm/GermplasmSearch_GET.md" 
 	       "Germplasm/GermplasmSearch_POST.md"
@@ -58,8 +61,6 @@ sources=("README.md"
 	       "Programs/README.md"
 	       "Programs/ListPrograms.md"
 	       "Programs/ProgramSearch.md"
-	       "Crops/README.md"
-	       "Crops/ListCrops.md"
 	       "Trials/README.md"
 	       "Trials/ListTrialSummaries.md"
 	       "Trials/GetTrialById.md"

diff --git a/Scripts/buildGitHubReadMe.sh b/Scripts/buildGitHubReadMe.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+if [ -d "$1" ]; then
+	ROOT_DIRECTORY=${1};
+else
+	ROOT_DIRECTORY=${HOME};
+fi
+
+BRAPI_DIR=${ROOT_DIRECTORY}
+
+BRAPI_FILE=${ROOT_DIRECTORY}/Specification/README.md
+
+if [ -f $BRAPI_FILE ]; then
+    rm $BRAPI_FILE
+fi
+touch $BRAPI_FILE
+
+# Tedious to write out the names of all the directories and files but this let's us control the order of assembly
+BRAPI_PREFIX=${BRAPI_DIR}/Specification/
+
+sources=(  "GeneralInfo/Intro.md"
+	       "GeneralInfo/URL_Structure.md"
+	       "GeneralInfo/Response_Structure.md"
+	       "GeneralInfo/Error_Handling.md"
+	       "GeneralInfo/Date_Time_Encoding.md"
+	       "GeneralInfo/Location_Encoding.md"
+	       "GeneralInfo/Search_Services.md"
+	       "GeneralInfo/Asychronous_Processing.md"
+) 
+
+for i in ${sources[@]}; do
+    echo $BRAPI_PREFIX$i;
+    cat $BRAPI_PREFIX$i >> $BRAPI_FILE;
+    echo "" >> $BRAPI_FILE;
+done
+
+echo $BRAPI_FILE
diff --git a/Specification/Calls/Calls.md b/Specification/Calls/Calls.md
@@ -1,10 +1,6 @@
 ## Call Search [/brapi/v1/calls]
 
-Status: ACCEPTED
-
-Implemented by: Germinate, Cassavabase
-
-Used by: Flapjack
+This call is **required** for every unique BrAPI implementation server. 
 
 ##### Response data types
 |Variable|Datatype|Description|Required|

diff --git a/Specification/Crops/CommonCropNames_GET.md b/Specification/Crops/CommonCropNames_GET.md
@@ -0,0 +1,34 @@
+## List supported crops [/brapi/v1/commonCropNames]
+
+List the common crop names for the crops available in a database server. 
+
+This call is **required** for multi-crop systems where data from multiple crops may be stored in the same database server. A distinct database server is defined by everything in the URL before "/brapi/v1", including host name and base path.  
+
+This call is recommended for single crop systems to be compatible with multi-crop clients. For a single crop system the response should contain an array with exactly 1 element. 
+
+The common crop name can be used as a search parameter for Programs, Studies, and Germplasm.
+
+### List supported crops [GET /brapi/v1/commonCropNames{?pageSize}{?page}]
++ Parameters
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
+
++ Response 200 (application/json)
+
+        {
+            "metadata": {
+                "pagination": {
+                    "pageSize": 1000,
+                    "currentPage": 0,
+                    "totalCount": 3,
+                    "totalPages": 1
+                },
+                "status" : [],
+                "datafiles": []
+            },
+            "result": {
+                "data": [
+                    "maize", "wheat", "rice"
+                ]
+            }
+        }
diff --git a/Specification/Crops/ListCrops.md → Specification/Crops/ListCrops_Deprecated.md b/Specification/Crops/ListCrops.md → Specification/Crops/ListCrops_Deprecated.md
@@ -1,8 +1,4 @@
-## List supported crops [/brapi/v1/crops]
-Scope: CORE.
-Status: ACCEPTED.
-
-### List supported crops [GET /brapi/v1/crops{?pageSize}{?page}]
+### **Deprecated** List supported crops [GET /brapi/v1/crops{?pageSize}{?page}]
 + Parameters
    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
    + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.

diff --git a/Specification/GeneralInfo/Intro.md b/Specification/GeneralInfo/Intro.md
@@ -0,0 +1,5 @@
+FORMAT: 1A
+
+# BrAPI V1.2
+
+The Breeding API specifies a standard interface for plant phenotype/genotype databases to serve their data to crop breeding applications. It is a <i>shared</i>, <i>open</i> API, to be used by all data providers and data consumers who wish to participate. Initiated in May 2014, it is currently in an actively developing state, so now is the time for potential participants to help shape the specifications to ensure their needs are addressed. For more information, go to <a href="https://brapi.org/">brapi.org</a>.
diff --git a/Specification/GeneralInfo/URL_Structure.md b/Specification/GeneralInfo/URL_Structure.md
@@ -2,13 +2,14 @@
 
 API requests are structured as 
 
-"https://_\<server\>_/brapi/v1/_\<call\>_"
+https://**_\<server\>_**/brapi/v1/**_\<call\>_**
 
-where "v1" is the major version number of the API, followed by the desired REST call.
+where "v1" is the major version number of the API, followed by the desired REST `<call>`.
 
-Example: https://test-server.brapi.org/brapi/v1/markerprofiles/2939 
+Example: _https://test-server.brapi.org/brapi/v1/markerprofiles/2939_ 
 
-To distinguish between multiple databases available from the same server, include the database name as part of the "\<server\>" identifier. An arbitrary number of levels can be inserted between the domain name and the brapi level, if needed.
+To distinguish between multiple databases available from the same server, include a base path as part of the `<server>` identifier. An arbitrary number of levels can be inserted between the domain name and the brapi level, if needed.
 
-Example: test-server.brapi.org/maize\_db\_01/brapi/v1/markerprofiles/2939
-Example: test-server.brapi.org/cornell/cips/wheat_db/brapi/v1/markerprofiles/2939
+Example: _https://test-server.brapi.org/**maize\_db\_01**/brapi/v1/markerprofiles/2939_
+
+Example: _https://test-server.brapi.org/**cornell/cals/wheat_db**/brapi/v1/markerprofiles/2939_
diff --git a/Specification/Germplasm/GermplasmSearch_GET.md b/Specification/Germplasm/GermplasmSearch_GET.md
@@ -38,19 +38,20 @@ Adresses these needs:
 |species|string|[MCPD](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) Specific epithet portion of the scientific name in lowercase letters.||
 |taxonIds|array| The list of IDs for this SPECIES from different sources. If present, NCBI Taxon should be always listed as "ncbiTaxon" preferably with a purl. The rank of this ID should be species.||
 |speciesAuthority|string|[MCDP](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf)||
-|subtaxa|string|[MCPD](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) Subtaxon can be used to store any additional taxonomic identifier. The following abbreviations are allowed: ‘subsp.’ (for subspecies); ‘convar.’ (for convariety); ‘var.’ (for variety); ‘f.’ (for form); ‘Group’ (for ‘cultivar group’).|
+|subtaxa|string|[MCPD](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) Subtaxon can be used to store any additional taxonomic identifier. The following abbreviations are allowed: "subsp." (for subspecies); "convar." (for convariety); "var." (for variety); "f." (for form); "Group" (for "cultivar group").|
 |subtaxaAuthority|string|[MCDP](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) ||
 |donors|array of object|[MCPD](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) code of the donor institute and Identifier assigned to an accession by the donor, and permanent identifier.||
 |acquisitionDate|string|[MCPD](https://www.bioversityinternational.org/fileadmin/user_upload/online_library/publications/pdfs/FAOBIOVERSITY_MULTI-CROP_PASSPORT_DESCRIPTORS_V.2.1_2015_2020.pdf) Follow ISO 8601 standard|
 
-### Germplasm search through GET [GET /brapi/v1/germplasm-search{?germplasmPUI}{?germplasmDbId}{?germplasmName}{?pageSize}{?page}]
+### Germplasm search through GET [GET /brapi/v1/germplasm-search{?germplasmPUI}{?germplasmDbId}{?germplasmName}{?commonCropName}{?pageSize}{?page}]
 
 Use GET when parameter size is less than 2K bytes.
 
 + Parameters
    + germplasmPUI (optional, string, `http://data.inra.fr/accession/234Col342`) ... Permanent unique identifier (DOI, URI, etc.)
    + germplasmDbId (optional, string, `986`) ... Internal database identifier
    + germplasmName (optional, string, `Pahang`) ... Name of the germplasm
+   + commonCropName (optional, string, `banana`) ... The common crop name. Important for multi-crop systems.
    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
    + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 

diff --git a/Specification/Germplasm/GermplasmSearch_POST.md b/Specification/Germplasm/GermplasmSearch_POST.md
@@ -11,6 +11,7 @@ Use POST for large queries (>2K bytes).
             "germplasmGenus" : [ "Solanum", "Triticum" ],
             "germplasmNames" : [ "XYZ1", "Pahang" ],
             "accessionNumbers": [ "ITC0609", "ITC0685" ],
+            "commonCropName": "wheat",
             "pageSize" : 100,
             "page": 1
         }

diff --git a/Specification/Programs/ListPrograms.md b/Specification/Programs/ListPrograms.md
@@ -4,11 +4,12 @@ Call to retrieve a list of programs.
 Status: ACCEPTED
 Implemented By:
 
-### List programs [GET /brapi/v1/programs{?programName}{?abbreviation}{?pageSize}{?page}]
+### List programs [GET /brapi/v1/programs{?programName}{?abbreviation}{?commonCropName}{?pageSize}{?page}]
 
 + Parameters
     + programName (optional, string, `Internation Yield Trial`) ... Filter by program name. Exact match.
     + abbreviation (optional, string, `IYT`) ... Filter by program abbreviation. Exact match.
+    + commonCropName (optional, string, `wheat`) ... The common crop name. Important for multi-crop systems.
     + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
     + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
@@ -32,14 +33,16 @@ Implemented By:
                         "name": "Wheat Resistance Program",
                         "abbreviation" : "DRP1",
                         "objective" : "Disease resistance",
-                        "leadPerson" : "Dr. Henry Beachell"
+                        "leadPerson" : "Dr. Henry Beachell",
+                        "commonCropName": "wheat"
                     },
                     {
                         "programDbId": "456",
                         "name": "Wheat Improvement Program",
                         "abbreviation" : "DRP2",
                         "objective" : "Yield improvement",
-                        "leadPerson" : "Dr. Norman Borlaug"
+                        "leadPerson" : "Dr. Norman Borlaug",
+                        "commonCropName": "wheat"
                     }
                 ]
             }

diff --git a/Specification/Programs/ProgramSearch.md b/Specification/Programs/ProgramSearch.md
@@ -15,6 +15,7 @@ See <a href="#introduction/search-services">Search Services</a> for additional i
             "abbreviation" : "DRP1",
             "objective" : "Disease resistance",
             "leadPerson" : "Dr. Henry Beachell",
+            "commonCropName": "wheat",
             "pageSize": 1000,
             "page": 0
         }
@@ -39,14 +40,16 @@ See <a href="#introduction/search-services">Search Services</a> for additional i
                         "name": "Wheat Resistance Program",
                         "abbreviation" : "DRP1",
                         "objective" : "Disease resistance",
-                        "leadPerson" : "Dr. Henry Beachell"
+                        "leadPerson" : "Dr. Henry Beachell",
+                        "commonCropName": "wheat"
                     },
                     {
                         "programDbId": "456",
                         "name": "Wheat Improvement Program",
                         "abbreviation" : "DRP2",
                         "objective" : "Yield improvement",
-                        "leadPerson" : "Dr. Norman Borlaug"
+                        "leadPerson" : "Dr. Norman Borlaug",
+                        "commonCropName": "wheat"
                     }
                 ]
             }