diff --git a/Scripts/buildBrapiBlueprint.sh b/Scripts/buildBrapiBlueprint.sh index 90a71d0d..97f0c844 100755 --- 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 new file mode 100644 index 00000000..d565f202 --- /dev/null +++ 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 \ No newline at end of file diff --git a/Specification/Calls/Calls.md b/Specification/Calls/Calls.md index 0578be03..49511477 100644 --- 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 new file mode 100644 index 00000000..553bd8f3 --- /dev/null +++ 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 b/Specification/Crops/ListCrops_Deprecated.md similarity index 84% rename from Specification/Crops/ListCrops.md rename to Specification/Crops/ListCrops_Deprecated.md index e71a9e7f..966e4299 100644 --- a/Specification/Crops/ListCrops.md +++ b/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 new file mode 100644 index 00000000..ad671d34 --- /dev/null +++ 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 shared, open 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 brapi.org. diff --git a/Specification/GeneralInfo/URL_Structure.md b/Specification/GeneralInfo/URL_Structure.md index 01ff76cb..fa5cd85a 100644 --- a/Specification/GeneralInfo/URL_Structure.md +++ b/Specification/GeneralInfo/URL_Structure.md @@ -2,13 +2,14 @@ API requests are structured as -"https://_\_/brapi/v1/_\_" +https://**_\_**/brapi/v1/**_\_** -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 ``. -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 "\" 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 `` 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 \ No newline at end of file +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_ \ No newline at end of file diff --git a/Specification/Germplasm/GermplasmSearch_GET.md b/Specification/Germplasm/GermplasmSearch_GET.md index 61807593..4538c196 100644 --- a/Specification/Germplasm/GermplasmSearch_GET.md +++ b/Specification/Germplasm/GermplasmSearch_GET.md @@ -38,12 +38,12 @@ 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. @@ -51,6 +51,7 @@ Use GET when parameter size is less than 2K bytes. + 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 index cc6aa5eb..00403b52 100644 --- 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 index 4419f03e..b2e1d2d2 100644 --- 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 index fb7ca1b5..584de3c3 100644 --- a/Specification/Programs/ProgramSearch.md +++ b/Specification/Programs/ProgramSearch.md @@ -15,6 +15,7 @@ See Search Services for additional i "abbreviation" : "DRP1", "objective" : "Disease resistance", "leadPerson" : "Dr. Henry Beachell", + "commonCropName": "wheat", "pageSize": 1000, "page": 0 } @@ -39,14 +40,16 @@ See Search Services 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" } ] } diff --git a/Specification/README.md b/Specification/README.md index ad671d34..92cc4b4d 100644 --- a/Specification/README.md +++ b/Specification/README.md @@ -3,3 +3,319 @@ 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 shared, open 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 brapi.org. + +### URL structure + +API requests are structured as + +https://**_\_**/brapi/v1/**_\_** + +where "v1" is the major version number of the API, followed by the desired REST ``. + +Example: _https://test-server.brapi.org/brapi/v1/markerprofiles/2939_ + +To distinguish between multiple databases available from the same server, include a base path as part of the `` identifier. An arbitrary number of levels can be inserted between the domain name and the brapi level, if needed. + +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_ + +### Structure of the response object: + +The return objects are encoded in JSON. The response consists of: ++ A "metadata" key containing pagination, status, and file information; ++ A "result" key that can contain: + + Arbitrary properties; and/or + + A "data" key containing an array of objects of the same type. + + +#### The Metadata Key + +The metadata key is structured as followed: + + +```` + "metadata" : { + "pagination" : { + "totalCount" : 1234, + // total number of elements available in the super set (unpaged) + "pageSize" : 200, + // number of elements in the current returned page + "totalPages" : 7, + // total number of pages available (total count / requested page size) + "currentPage" : 2 + // index number of the current returned page + }, + "status" : [ + { + "code" : "200", + "message" : "Success" + } + ], + "asynchStatus": { + "asynchId": "abc123" + "status": "PENDING", + "startTime": "2017-06-16T14:47:23-0600", + "endTime": null, + "percentComplete": 0 + }, + "datafiles" : ["/mnt/local/matrix_01.csv", + "/mnt/local/matrix_02.csv"] + } + +```` + ++ **pagination**: The `pagination` object is applicable only when the payload contains a "data" key. It describes the pagination of the data contained in the "data" array, as a way to identify which subset of data is being returned. Pages are zero indexed, so the first page will be page 0 (zero). + ++ **datafiles**: The `datafiles` key contains a list of file paths, which can be relative or complete URLs. These files contain additional information related to the returned object and can be retrieved by a subsequent call. The empty list should be returned if no additional data files are present. + ++ **status**: The `status` object contains a list of objects with the keys "code" and "message". If no status is reported, an empty list should be returned. + +**NOTE:** The Status object should be used _in addition_ to the standard [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). The purpose is to provide additional, BrAPI specific information back to the client. + +The following are officially accepted status codes, though others maybe used for specific implementation needs. + +Code|Message|Description +--|--|-- +200|"Success"|Optional status for representing explicitly that the request was accepted and returned without any issue +2001|"Upload Successful"|New data was submitted to and accepted by the server +2002|"Async call in progress"|An Async call has been successfully started, See the section on Asynchronous Calls for more details. +400|"Failure"|Optional status for representing explicitly that the request was bad in some way +4001|"Could not update values for "| Error to be returned when the server is unable to store some data submitted +4002|"Missing required parameter "| Error to be returned when a required parameter is missing from request +4003|"Permission Denied"| Error to be returned when the user does not have permission to access the requested resource +4004|"No objects found for given parameters"| Error to be returned when there are no objects in the database which match the requested search parameters + + ++ **asynchStatus**: (Optional) The `asynchStatus` object is used to provide additional information around certain calls being performed asynchronously. See the section on Asynchronous Calls for more details. + + + +#### Payload + +The BRAPI response payload, which is contained in the "result" key, allows for three different types of responses: ++ **master**: In this type of response, the "result" key consists of arbitrary properties without a "data" key (in this case, pagination does not apply). +```` +{ + "metadata" : { + "pagination" : { + "totalCount" : 0, + "pageSize" : 0, + "totalPages" : 0, + "currentPage" : 0 + }, + "status" : [ ], + "datafiles" : [ ] + }, + "result" : { + "key0": "master", + "key1": 20, + "key2": [ "foo", "bar", "baz" ] + } +} +```` ++ **detail**: In this type of response, the "result" element only contains the "data" key, which is an arbitrarily long array of objects of the same type. +```` +{ + "metadata" : { + "pagination" : { + "totalCount" : 20, + "pageSize" : 3, + "totalPages" : 7, + "currentPage" : 0 + }, + "status" : [ ], + "datafiles" : [ ] + }, + "result" : { + "data" : [ + { + "detailKey0" : "detail0", + "detailKey1" : [ "foo", "bar" ] + }, + { + "detailKey0" : "detail1", + "detailKey1" : [ "bar", "baz" ] + }, + { + "detailKey0" : "detail2", + "detailKey1" : [ "baz", "foo" ] + }, + ] + } +} +```` + ++ **master/detail**: In this type of response, the "result" key contains both arbtirary properties and the "data" key. +```` +{ + "metadata" : { + "pagination" : { + "totalCount" : 20, + "pageSize" : 3, + "totalPages" : 7, + "currentPage" : 0 + }, + "status" : [ ], + "datafiles" : [ ] + }, +"result" : { + "key0": "master", + "key1": 20, + "key2": [ "foo", "bar", "baz" ], + "data" : [ + { + "detailKey0" : "detail0", + "detailKey1" : [ "foo", "bar" ] + }, + { + "detailKey0" : "detail1", + "detailKey1" : [ "bar", "baz" ] + }, + { + "detailKey0" : "detail2", + "detailKey1" : [ "baz", "foo" ] + }, + ] + } +} +```` + +Additional documentation is in the [GitHub wiki](https://github.com/plantbreeding/documentation/wiki). +See especially the [Best Practices and Conventions] +(https://github.com/plantbreeding/documentation/wiki/Best-Practices-and-Conventions). + + +### Error Handling + +HTTP error codes are used as required, e.g., 200 for ok, 404 for page not found, 401 for not authorized, 501 for not implemented, 201 for created in a PUT, 202 for request received but not yet processed, etc. + +All capturable errors should be responded to with the appropriate HTTP error code and a well formulated JSON structure that includes a message describing the error. The error code is intended as a debugging tool for the service provider. + +### Date and timestamp fields + +Date and timestamp fields are coded in the ISO 8601 standard, extended format. If the field name ends in "Date", only the date portion should be provided, for example "2017-06-16". If a field ends in "Timestamp", the date, time and time zone information needs to be provided, as in this example: "2017-06-16T14:47:23-0600". In version 1, milliseconds are not supported. +--|Format|Example +--|--|-- +Date|yyyy-MM-dd|2017-06-16 +Timestamp|yyyy-MM-ddThh:mm:ssz|2017-06-16T14:47:23-0600 +Timestamp UTC|yyyy-MM-ddThh:mm:ssZ|2017-06-16T20:47:23Z + + +### Location coordinate encoding + +To encode locations as coordinates, the ISO 6709 standard is used. Importantly, the decimal notation is used. Example +latitude: +40.20361, longitude: -075.00417. Note that plus and minus signs are always required, and latitude has two digits before the decimal separator (with leading zeroes when necessary), and longitude has three digits. + + +### Search Services + +There are several "Search" calls specified in BrAPI. These calls have a postfix of "-search" in the name, and are used to search for a set of entities without knowing the primary key (DbId). These calls can be used when presenting search options to a user, or when a system needs to access an entity using a candidate key which is not the DbId. All search calls should have a set of optional parameters, which are specific to that entity and its fields. + +Each optional parameter included in any search service call should act as a filter on the data being returned. This means the search parameters should always have an 'AND' type relationship with each other. + +If NO parameters are used in the request, the search service should return ALL entities of the given type, since no filters are being applied. (Normal pagination defaults still apply) + +Example: Given this data +``` +{ + id: "1", + first: "Bob", + last: "Jones" +},{ + id: "2", + first: "Bob", + last: "Smith" +},{ + id: "3", + first: "Alice", + last: "Jones" +},{ + id: "4", + first: "Cathy", + last: "Jones" +} +``` +The call `/person-search?first=Bob&last=Jones` will only return entity "1". The parameter `first` filters the data to just entities where the first name is "Bob" (entities "1" and "2"). The parameter `last` is an additional filter and further limits the data returned, resulting in just entity "1" satisfying both filters. + +When parameters are defined as lists, each item in the list acts as an accepted value for that parameter. This can be thought of as an 'OR' relationship for items within the same list parameter, or it could be considered a 'value IN array' type operation by a database. + +For example: Given the data above, the call `/person-search?first=Alice,Bob&last=Jones` will return entities "1" and "3". In this case, the parameter `first` filters the data to the first 3 entities, including all entities where the first name is 'Alice' OR 'Bob'. Again, the parameter `last` is an additional filter, further limiting the data returned, resulting in just entities "1" and "3" satisfying both filters. + +These rules for search parameters apply to both GET call query parameters and POST call body parameters. + + + +### Asynchronous Processing + +Some search calls initiate asynchronous processing, which take an indeterminate amount of time to complete. + +Calls which could have asynchronous implementations: ++ GET /allelematrix-search ++ POST /allelematrix-search + +If a search call has an asynchronous implementation, then the `asynchStatus` object in `metadata` must be populated. ++ The `asynchId` (required) key will contain an id that will be used in additional polling status calls. ++ The `status` (required) key will contain one of the following possible states with the specified meanings: + + PENDING: The background process has not started to work on the job; + + INPROCESS: The background process is working on the job; + + FINISHED: The job has completed successfully, in which case the `result` object will be populated with the requested data OR the `datafiles` array will have at least one data file URI which contains the requested data. + + FAILED: The job has failed; ++ The `startTime` indicates the date and time when the call was first made. ++ The `endTime` indicates the date and time when the processing for the call is complete. ++ The `percentComplete` is an integer [range 0-100] which indicates how much of the process has completed. If a system has no way of detecting intermediate status, `percentComplete` may jump directly from 0 to 100 when processing is finished. + +After making the initial asynch call and receiving an `asynchId`, all subsequent polling calls should go to `/asynch_call/{asynchId}` + +For example, a call to **`/allelematrix-search`** might give the following response: + +```` +{ + "metadata": { + "pagination": { + "pageSize": 0, + "currentPage": 0, + "totalCount": 0, + "totalPages": 0 + }, + "status": [{"code": "2002", + "message" : "Asynchronous call in progress"}], + "datafiles": [], + "asynchStatus": { + "asynchId": "abc123", + "status": "PENDING", + "startTime": "2017-06-16T14:47:23-0600", + "endTime": null, + "percentComplete": 0 + } + }, + "result" : {} +} +```` + +Given this response, a GET on the resource **`/allelematrix-search/abc123`** will give a response as follows: + +```` +{ + "metadata": { + "pagination": { + "pageSize": 0, + "currentPage": 0, + "totalCount": 0, + "totalPages": 0 + }, + "status": [{"code" : "200" , + "message" : "FINISHED"}], + "datafiles": ["https://example.org/shared_files/crops/rice/extract/output/721"], + "asynchStatus": { + "asynchId": "abc123", + "status": "FINISHED", + "startTime": "2017-06-16T14:47:23-0600", + "endTime": "2017-06-16T14:49:65-0600", + "percentComplete": 100 + } + }, + "result" : {} +} +```` + diff --git a/Specification/Studies/StudiesSearch_GET.md b/Specification/Studies/StudiesSearch_GET.md index 503e9d8d..57b550a8 100644 --- a/Specification/Studies/StudiesSearch_GET.md +++ b/Specification/Studies/StudiesSearch_GET.md @@ -13,13 +13,14 @@ Get list of studies StartDate and endDate should be ISO8601 format for dates: YYYY-MM-DD -### Search Studies (GET) [GET /brapi/v1/studies-search{?studyDbId}{?trialDbId}{?programDbId}{?locationDbId}{?seasonDbId}{?studyType}{?germplasmDbIds}{?observationVariableDbIds}{?pageSize}{?page}{?active}{?sortBy}{?sortOrder}] +### Search Studies (GET) [GET /brapi/v1/studies-search{?studyDbId}{?trialDbId}{?programDbId}{?commonCropName}{?locationDbId}{?seasonDbId}{?studyType}{?germplasmDbIds}{?observationVariableDbIds}{?pageSize}{?page}{?active}{?sortBy}{?sortOrder}] + Parameters + studyDbId (optional, string, `35`) ... DbId for a study + trialDbId (optional, string, `7`) ... Filter by trial + programDbId (optional, string, `1`) ... Program filter to only return studies associated with given program id. + + commonCropName (optional, string, `banana`) ... The common crop name from the Program. Important for multi-crop systems. + locationDbId (optional, string, `212`) ... Filter by location + seasonDbId (optional, string, `2016E`) ... Filter by season or year + studyType (optional, string, `Nursery`) ... Filter based on study type e.g. Nursery, Trial or Genotype. diff --git a/Specification/Studies/StudiesSearch_POST.md b/Specification/Studies/StudiesSearch_POST.md index 5ff12d4d..bfc7c0e3 100644 --- a/Specification/Studies/StudiesSearch_POST.md +++ b/Specification/Studies/StudiesSearch_POST.md @@ -12,6 +12,7 @@ "studyNames" : ["Study A", "StydyB"], "studyLocations" : ["Kenya", "Zimbabwe"], "programNames": ["Test Program", "Program2"], + "commonCropName": "wheat", "germplasmDbIds" : [ "CML123", "CWL123"], "observationVariableDbIds": ["CO-PH-123", "Var-123"] "active" : "true",