From f6b6888f695b8012006989ec860c77f25f28df54 Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Wed, 15 Dec 2021 14:25:38 -0600 Subject: [PATCH 1/7] new webpage for api --- .../documentation/api-gateway.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 website/docs/developer/development-guide/documentation/api-gateway.md diff --git a/website/docs/developer/development-guide/documentation/api-gateway.md b/website/docs/developer/development-guide/documentation/api-gateway.md new file mode 100644 index 000000000..9fd23a86e --- /dev/null +++ b/website/docs/developer/development-guide/documentation/api-gateway.md @@ -0,0 +1,105 @@ +--- +id: API gateway paths, inputs and outputs +title: API Gateway paths, inputs and outputs +description: Additional notes on API gateway paths, inputs and expected outputs. +--- + +## Overview + +This documentation provides details on the paths, input and outputs for the `orca_api` API gateway. The format for the API invoke URL is `https://example.execute-api.us-west-2.amazonaws.com/[stage_name]/[path]`. Check [API gateway research webpage](https://github.com/nasa/cumulus-orca/blob/master/website/docs/developer/research/research-APIGateway.md) for more information. + +## Path +- The path `catalog/reconcile` of `orca_api` API gateway returns additional metadata information needed for reporting by triggering the `orca_catalog_reporting` lambda. +- The path `recovery/granules` of `orca_api` API gateway returns detailed status of the granule by triggering the `request_status_for_granule` lambda. +- The path `recovery/jobs` of `orca_api` API gateway returns detailed status for a particular recovery job by triggering the `request_status_for_job` lambda. + +### Inputs and outputs +The API invoke URL can be found under `Stages` section in API gateway UI. All APIs use the `POST` method. + +- Catalog reporting API invoke URL example: +`https://example.execute-api.us-west-2.amazonaws.com/orca/catalog/reconcile` + +- Catalog reporting API output example: +```json +{ + "anotherPage": false, + "granules": [ + { + "providerId": "lpdaac", + "collectionId": "MOD14A1___061", + "id": "MOD14A1.061.A23V45.2020235", + "createdAt": "628021850000", + "executionId": "u654-123-Yx679", + "ingestDate": "628021950000", + "lastUpdate": "628021970000", + "files": [ + { + "name": "MOD14A1.061.A23V45.2020235.2020240145621.hdf", + "cumulusArchiveLocation": "cumulus-bucket", + "orcaArchiveLocation": "orca-archive", + "keyPath": "MOD14A1/061/032/MOD14A1.061.A23V45.2020235.2020240145621.hdf", + "sizeBytes": 100934568723, + "hash": "ACFH325128030192834127347", + "hashType": "SHA-256", + "version": "VXCDEG902" + } + ] + } + ] +} + +``` + +- Recovery granules invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` + +- Recovery granules API output example: +```json +{ + "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", + "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85", + "files": [ + { + "file_name": "f1.doc", + "status": "pending" + }, + { + "file_name": "f2.pdf", + "status": "failed", + "error_message": "Access Denied" + }, + { + "file_name": "f3.txt", + "status": "success" + } + ], + "restore_destination": "bucket_name", + "request_time": 628021800000, + "completion_time": 628021900000 +} + +``` + +- Recovery job API invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` + +- Recovery job API output example: +```json +{ + "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85", + "job_status_totals": { + "pending": 1, + "success": 1, + "failed": 1 + }, + "granules": [ + { + "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", + "status": "failed" + }, + { + "granule_id": "b5681dc1-48ba-4dc3-877d-1b5ad97e8276", + "status": "pending" + } + ] +} + +``` \ No newline at end of file From 40f4391a4394d24cefbdfd9aacfcfd504a76c562 Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Wed, 15 Dec 2021 14:51:45 -0600 Subject: [PATCH 2/7] minor fix --- .../development-guide/documentation/api-gateway.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/developer/development-guide/documentation/api-gateway.md b/website/docs/developer/development-guide/documentation/api-gateway.md index 9fd23a86e..0adf061ee 100644 --- a/website/docs/developer/development-guide/documentation/api-gateway.md +++ b/website/docs/developer/development-guide/documentation/api-gateway.md @@ -16,7 +16,7 @@ This documentation provides details on the paths, input and outputs for the `orc ### Inputs and outputs The API invoke URL can be found under `Stages` section in API gateway UI. All APIs use the `POST` method. -- Catalog reporting API invoke URL example: +- Catalog reporting API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/catalog/reconcile` - Catalog reporting API output example: @@ -50,7 +50,7 @@ The API invoke URL can be found under `Stages` section in API gateway UI. All AP ``` -- Recovery granules invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` +- Recovery granules API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` - Recovery granules API output example: ```json @@ -79,7 +79,7 @@ The API invoke URL can be found under `Stages` section in API gateway UI. All AP ``` -- Recovery job API invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` +- Recovery job API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` - Recovery job API output example: ```json From a8d0654c5bc6dc03a9164829d1f05ecd2e35226e Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Wed, 15 Dec 2021 15:13:32 -0600 Subject: [PATCH 3/7] changed api gateway dir --- .../{development-guide/documentation => api}/api-gateway.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename website/docs/developer/{development-guide/documentation => api}/api-gateway.md (100%) diff --git a/website/docs/developer/development-guide/documentation/api-gateway.md b/website/docs/developer/api/api-gateway.md similarity index 100% rename from website/docs/developer/development-guide/documentation/api-gateway.md rename to website/docs/developer/api/api-gateway.md From 74ef69333b22ceab2f49abb625edfada6ac9dd5b Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Thu, 16 Dec 2021 15:49:22 -0600 Subject: [PATCH 4/7] addressed PR comments --- website/docs/developer/api/api-gateway.md | 90 ++++++++++++++++++----- website/sidebars.js | 3 + 2 files changed, 75 insertions(+), 18 deletions(-) diff --git a/website/docs/developer/api/api-gateway.md b/website/docs/developer/api/api-gateway.md index 0adf061ee..ea62caae1 100644 --- a/website/docs/developer/api/api-gateway.md +++ b/website/docs/developer/api/api-gateway.md @@ -1,25 +1,32 @@ --- -id: API gateway paths, inputs and outputs -title: API Gateway paths, inputs and outputs -description: Additional notes on API gateway paths, inputs and expected outputs. +id: orca-api +title: ORCA API Reference +description: ORCA API reference for developers that provides API documentation and interactions. --- ## Overview -This documentation provides details on the paths, input and outputs for the `orca_api` API gateway. The format for the API invoke URL is `https://example.execute-api.us-west-2.amazonaws.com/[stage_name]/[path]`. Check [API gateway research webpage](https://github.com/nasa/cumulus-orca/blob/master/website/docs/developer/research/research-APIGateway.md) for more information. +The purpose of this page is to give developers information on how to use the ORCA API and explain the expected inputs, outputs and paths. The API can be used to get metadata information about a granule or a recovery job and accepts and responds with JSON payloads at various HTTPS endpoints. All ORCA APIs use the `POST` method. -## Path -- The path `catalog/reconcile` of `orca_api` API gateway returns additional metadata information needed for reporting by triggering the `orca_catalog_reporting` lambda. -- The path `recovery/granules` of `orca_api` API gateway returns detailed status of the granule by triggering the `request_status_for_granule` lambda. -- The path `recovery/jobs` of `orca_api` API gateway returns detailed status for a particular recovery job by triggering the `request_status_for_job` lambda. -### Inputs and outputs -The API invoke URL can be found under `Stages` section in API gateway UI. All APIs use the `POST` method. +## Catalog reporting API -- Catalog reporting API input invoke URL example: +The `catalog/reconcile` API call provides a user with the current listing of the ORCA catalog that can be used to reconcile granule and file information against a master catalog. For example, comparing the Cumulus primary archive holdings against the ORCA holdings to find discrepancies. +Catalog reporting API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/catalog/reconcile` -- Catalog reporting API output example: +#### Required input fields +- pageIndex(int)- The 0-based index of the results page to return. +- endTimestamp(int)- Cumulus granule createdAt end-time for date range to compare data, in milliseconds since 1 January 1970 UTC. + +#### Optional input fields +- providerId(str)- The unique ID of the provider making the request. +- collectionId(str)- The unique ID of collection to compare. +- granuleId(str)- The unique ID of granule to compare. +- startTimestamp(int)- Cumulus granule createdAt start time for date range to compare data, in milliseconds since 1 January 1970 UTC. + + +Catalog reporting API output example: ```json { "anotherPage": false, @@ -49,10 +56,38 @@ The API invoke URL can be found under `Stages` section in API gateway UI. All AP } ``` +where +- anotherPage(Boolean)- Indicates if more results can be retrieved on another page. +- providerId(str)- The unique ID of the provider making the request. +- collectionId(str)- The unique ID of collection to compare. +- id(str)- The unique ID of the granule. +- createdAt(int)- The time, in milliseconds since 1 January 1970 UTC, data was originally ingested into cumulus. +- executionId(str)- Step function execution ID from AWS. +- ingestDate(int)- The time, in milliseconds since 1 January 1970 UTC, that the data was originally ingested into ORCA. +- lastUpdate(int)- The time, in milliseconds since 1 January 1970 UTC, that information was updated. +- name(str)- The name and extension of the file. +- cumulusArchiveLocation(str)- Cumulus bucket the file resides in. +- orcaArchiveLocation(str)- ORCA S3 Glacier bucket the file resides in. +- keyPath(str)- S3 path to the file including the file name and extension, but not the bucket. +- sizeBytes(int)- Size in bytes of the file. From Cumulus ingest. +- hash(str)- Checksum hash of the file provided by Cumulus. +- hashType(str)- Hash type used to calculate the hash value of the file. +- version(str)- AWS provided version of the file. + + +## Recovery granules API + +The `recovery/granules` API call returns detailed status of the granule. -- Recovery granules API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` +Recovery granules API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` -- Recovery granules API output example: +#### Required input fields +- granule_id(str)- The unique ID of the granule to retrieve status for. + +#### Optional input fields +- asyncOperationId(str)- The unique ID of the asyncOperation. May apply to a request that covers multiple granules. + +Recovery granules API output example: ```json { "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", @@ -78,10 +113,25 @@ The API invoke URL can be found under `Stages` section in API gateway UI. All AP } ``` +where +- granule_id(str)- The unique ID of the granule retrieved. +- asyncOperationId(str)- The unique ID of the asyncOperation. +- file_name(str)- The name and extension of the file. +- status(str)- The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. +- error_message(str)- If the restoration of the file showed error, the error will be stored here. +- restore_destination(str)- The name of the glacier bucket the granule is being copied to. +- request_time(int)- The time, in milliseconds since 1 January 1970 UTC, when the request to restore the granule was initiated. +- completion_time(int)- The time, in milliseconds since 1 January 1970 UTC, when all granule_files were in an end state. + -- Recovery job API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` +## Recovery jobs API +The `recovery/jobs` API call returns detailed status for a particular recovery job. +Recovery job API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` -- Recovery job API output example: +#### Required input fields +- asyncOperationId(str)- The unique asyncOperationId of the recovery job. + +Recovery job API output example: ```json { "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85", @@ -101,5 +151,9 @@ The API invoke URL can be found under `Stages` section in API gateway UI. All AP } ] } - -``` \ No newline at end of file +``` +where +- asyncOperationId(str)- The unique asyncOperationId of the recovery job. +- job_status_totals(object)- Sums of how many granules are in each particular restoration status ('pending', 'staged', 'success', or 'failed'). +- granule_id(str)- The unique ID of the granule. +- status(str)- The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index 7cf725d03..27773fc1c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -70,6 +70,9 @@ module.exports = { 'developer/research/research-bamboo' ], + "API": [ + 'developer/api/orca-api' + ], }, cookbook: { "Getting Started": [ From 9328fc3bdce02519a2dbbd78ae42344ad68b7e87 Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Fri, 17 Dec 2021 09:23:42 -0600 Subject: [PATCH 5/7] changed formatting, added more instructions as per PR comments --- website/docs/developer/api/api-gateway.md | 160 ++++++++++++++-------- website/sidebars.js | 6 +- 2 files changed, 109 insertions(+), 57 deletions(-) diff --git a/website/docs/developer/api/api-gateway.md b/website/docs/developer/api/api-gateway.md index ea62caae1..598ee1d77 100644 --- a/website/docs/developer/api/api-gateway.md +++ b/website/docs/developer/api/api-gateway.md @@ -15,18 +15,30 @@ The `catalog/reconcile` API call provides a user with the current listing of the Catalog reporting API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/catalog/reconcile` -#### Required input fields -- pageIndex(int)- The 0-based index of the results page to return. -- endTimestamp(int)- Cumulus granule createdAt end-time for date range to compare data, in milliseconds since 1 January 1970 UTC. - -#### Optional input fields -- providerId(str)- The unique ID of the provider making the request. -- collectionId(str)- The unique ID of collection to compare. -- granuleId(str)- The unique ID of granule to compare. -- startTimestamp(int)- Cumulus granule createdAt start time for date range to compare data, in milliseconds since 1 January 1970 UTC. - - -Catalog reporting API output example: +### Catalog reporting API input +An example of the API input body is shown below: +```json +{ + "pageIndex": 0, + "providerId": ["lpdaac"], + "collectionId": ["MOD14A1__061"], + "granuleId": ["MOD14A1.061.A23V45.2020235"], + "startTimestamp": "628021800000", + "endTimestamp": "628021900000" +} +``` +The following table lists the fields in the input: +| Name | Data Type | Description | Required | +| ----------------| ----------- | --------------------------------------------------------------------------------------------------------------|----------| +| pageIndex | `int` | The 0-based index of the results page to return. | Yes | +| endTimestamp | `int` | Cumulus granule createdAt end-time for date range to compare data, in milliseconds since 1 January 1970 UTC. | Yes | +| providerId | `Array[str]` | The unique ID of the provider making the request. | No | +| collectionId | `Array[str]` | The unique ID of collection to compare. | No | +| granuleId | `Array[str]` | The unique ID of granule to compare. | No | +| startTimestamp | `int` | Cumulus granule createdAt start time for date range to compare data, in milliseconds since 1 January 1970 UTC.| No | + +### Catalog reporting API output +An example of the API output is shown below: ```json { "anotherPage": false, @@ -54,40 +66,56 @@ Catalog reporting API output example: } ] } - ``` -where -- anotherPage(Boolean)- Indicates if more results can be retrieved on another page. -- providerId(str)- The unique ID of the provider making the request. -- collectionId(str)- The unique ID of collection to compare. -- id(str)- The unique ID of the granule. -- createdAt(int)- The time, in milliseconds since 1 January 1970 UTC, data was originally ingested into cumulus. -- executionId(str)- Step function execution ID from AWS. -- ingestDate(int)- The time, in milliseconds since 1 January 1970 UTC, that the data was originally ingested into ORCA. -- lastUpdate(int)- The time, in milliseconds since 1 January 1970 UTC, that information was updated. -- name(str)- The name and extension of the file. -- cumulusArchiveLocation(str)- Cumulus bucket the file resides in. -- orcaArchiveLocation(str)- ORCA S3 Glacier bucket the file resides in. -- keyPath(str)- S3 path to the file including the file name and extension, but not the bucket. -- sizeBytes(int)- Size in bytes of the file. From Cumulus ingest. -- hash(str)- Checksum hash of the file provided by Cumulus. -- hashType(str)- Hash type used to calculate the hash value of the file. -- version(str)- AWS provided version of the file. - +The following table lists the fields in the output: + +| Name | Data Type | Description | +| --------------------------| ----------- | ----------------------------------------------------------------------------------------------------| +| anotherPage | `Boolean` | Indicates if more results can be retrieved on another page. | +| granules | `Array[Object]`| A list of objects representing individual files to copy. | +| -- providerId | `int` | The unique ID of the provider making the request. | +| -- collectionId | `str` | The unique ID of collection to compare. | +| -- id | `str` | The unique ID of the granule. | +| -- createdAt | `int` | The time, in milliseconds since 1 January 1970 UTC, data was originally ingested into cumulus. | +| -- executionId | `str` | Step function execution ID from AWS. | +| -- ingestDate | `int` | The time, in milliseconds since 1 January 1970 UTC, that the data was originally ingested into ORCA.| +| -- lastUpdate | `int` | The time, in milliseconds since 1 January 1970 UTC, that information was updated. | +| -- files | `Array[Object]`| Description and status of the files within the given granule. | +| -- name | `str` | The name and extension of the file. | +| -- cumulusArchiveLocation | `str` | Cumulus bucket the file resides in. | +| -- orcaArchiveLocation | `str` | ORCA S3 Glacier bucket the file resides in. | +| -- keyPath | `str` | S3 path to the file including the file name and extension, but not the bucket. | +| -- sizeBytes | `str` | Size in bytes of the file. From Cumulus ingest. | +| -- hash | `str` | Checksum hash of the file provided by Cumulus. | +| -- hashType | `str` | Hash type used to calculate the hash value of the file. | +| -- version | `str` | AWS provided version of the file. | + + +The API returns status code 200 on success, 400 if `pageIndex` or `endTimestamp` is missing and 500 if an error occurs when querying the database. ## Recovery granules API -The `recovery/granules` API call returns detailed status of the granule. +The `recovery/granules` API call relates to an ORCA recovery job status and returns detailed status of the granule. Recovery granules API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` -#### Required input fields -- granule_id(str)- The unique ID of the granule to retrieve status for. +### Catalog reporting API input +An example of the API input body is shown below: +```json +{ + "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", + "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85" +} +``` +The following table lists the fields in the input: +| Name | Data Type | Description | Required | +| ------------------| ----------- | -----------------------------------------------------------------------------------------|----------| +| granule_id | `str` | The unique ID of the granule to retrieve status for. | Yes | +| asyncOperationId | `str` | The unique ID of the asyncOperation. May apply to a request that covers multiple granules. | No | -#### Optional input fields -- asyncOperationId(str)- The unique ID of the asyncOperation. May apply to a request that covers multiple granules. -Recovery granules API output example: +### Recovery granules API output +An example of the API output is shown below: ```json { "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", @@ -113,25 +141,43 @@ Recovery granules API output example: } ``` -where -- granule_id(str)- The unique ID of the granule retrieved. -- asyncOperationId(str)- The unique ID of the asyncOperation. -- file_name(str)- The name and extension of the file. -- status(str)- The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. -- error_message(str)- If the restoration of the file showed error, the error will be stored here. -- restore_destination(str)- The name of the glacier bucket the granule is being copied to. -- request_time(int)- The time, in milliseconds since 1 January 1970 UTC, when the request to restore the granule was initiated. -- completion_time(int)- The time, in milliseconds since 1 January 1970 UTC, when all granule_files were in an end state. +The following table lists the fields in the output: + +| Name | Data Type | Description | +| -----------------------| -----------| ----------------------------------------------------------------------------------------------------| +| granule_id | `str` | The unique ID of the granule retrieved. | +| asyncOperationId | `str` | The unique ID of the asyncOperation. | +| files | `Array[Object]`| Description and status of the files within the given granule. | +| -- file_name | `str` | The name and extension of the file. | +| -- status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | +| error_message | `str` | If the restoration of the file showed error, the error will be stored here. | +| restore_destination | `str` | The name of the glacier bucket the granule is being copied to. | +| request_time | `int` | The time, in milliseconds since 1 January 1970 UTC, when the request to restore the granule was initiated.| +| completion_time | `int` | The time, in milliseconds since 1 January 1970 UTC, when all granule_files were in an end state. | + +The API returns status code 200 on success, 400 if `granule_id` is missing, 500 if an error occurs when querying the database and 404 if not found. ## Recovery jobs API The `recovery/jobs` API call returns detailed status for a particular recovery job. Recovery job API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/jobs` -#### Required input fields -- asyncOperationId(str)- The unique asyncOperationId of the recovery job. +### Recovery jobs API input +An example of the API input body is shown below: +```json +{ + "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85" +} +``` + +The following table lists the fields in the input: +| Name | Data Type | Description | Required | +| ------------------| ----------- | ----------------------------------------------------------|-----------| +| asyncOperationId | `str` | The unique ID of the asyncOperation of the recovery job. | Yes | -Recovery job API output example: + +### Recovery jobs API output +An example of the API output is shown below: ```json { "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85", @@ -152,8 +198,14 @@ Recovery job API output example: ] } ``` -where -- asyncOperationId(str)- The unique asyncOperationId of the recovery job. -- job_status_totals(object)- Sums of how many granules are in each particular restoration status ('pending', 'staged', 'success', or 'failed'). -- granule_id(str)- The unique ID of the granule. -- status(str)- The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. \ No newline at end of file +The following table lists the fields in the output: + +| Name | Data Type | Description | +| -----------------------| -----------| ----------------------------------------------------------------------------------------------------| +| asyncOperationId | `str` | The unique ID of the asyncOperation. | +| job_status_totals | `Object` |Sum of how many granules are in each particular restoration status ('pending', 'staged', 'success', or 'failed').| +| granules | `Array[Object]` | An array representing each granule being copied as part of the job. | +| -- granule_id | `str` | The unique ID of the granule retrieved. | +| -- status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | + +The API returns status code 200 on success, 400 if `asyncOperationId` is missing, 500 if an error occurs when querying the database and 404 if not found. diff --git a/website/sidebars.js b/website/sidebars.js index 27773fc1c..256a0604f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -59,6 +59,9 @@ module.exports = { 'developer/deployment-guide/testing_deployment', 'developer/deployment-guide/deploying-from-windows', ], + "API Reference": [ + 'developer/api/orca-api' + ], "Research": [ 'developer/research/research-intro', 'developer/research/research-localstack', @@ -70,9 +73,6 @@ module.exports = { 'developer/research/research-bamboo' ], - "API": [ - 'developer/api/orca-api' - ], }, cookbook: { "Getting Started": [ From 1525257118624592a9dd8493129d62dcdc5dd8b8 Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Fri, 17 Dec 2021 10:10:55 -0600 Subject: [PATCH 6/7] fixed formatting issues, addressed remaining PR comments --- website/docs/developer/api/api-gateway.md | 57 ++++++++++++----------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/website/docs/developer/api/api-gateway.md b/website/docs/developer/api/api-gateway.md index 598ee1d77..2b21f25a9 100644 --- a/website/docs/developer/api/api-gateway.md +++ b/website/docs/developer/api/api-gateway.md @@ -28,8 +28,9 @@ An example of the API input body is shown below: } ``` The following table lists the fields in the input: + | Name | Data Type | Description | Required | -| ----------------| ----------- | --------------------------------------------------------------------------------------------------------------|----------| +| ----------------| ------------|---------------------------------------------------------------------------------------------------------------|----------| | pageIndex | `int` | The 0-based index of the results page to return. | Yes | | endTimestamp | `int` | Cumulus granule createdAt end-time for date range to compare data, in milliseconds since 1 January 1970 UTC. | Yes | | providerId | `Array[str]` | The unique ID of the provider making the request. | No | @@ -58,7 +59,7 @@ An example of the API output is shown below: "orcaArchiveLocation": "orca-archive", "keyPath": "MOD14A1/061/032/MOD14A1.061.A23V45.2020235.2020240145621.hdf", "sizeBytes": 100934568723, - "hash": "ACFH325128030192834127347", + "hash": "ACFH325128030192834127347" "hashType": "SHA-256", "version": "VXCDEG902" } @@ -73,22 +74,22 @@ The following table lists the fields in the output: | --------------------------| ----------- | ----------------------------------------------------------------------------------------------------| | anotherPage | `Boolean` | Indicates if more results can be retrieved on another page. | | granules | `Array[Object]`| A list of objects representing individual files to copy. | -| -- providerId | `int` | The unique ID of the provider making the request. | -| -- collectionId | `str` | The unique ID of collection to compare. | -| -- id | `str` | The unique ID of the granule. | -| -- createdAt | `int` | The time, in milliseconds since 1 January 1970 UTC, data was originally ingested into cumulus. | -| -- executionId | `str` | Step function execution ID from AWS. | -| -- ingestDate | `int` | The time, in milliseconds since 1 January 1970 UTC, that the data was originally ingested into ORCA.| -| -- lastUpdate | `int` | The time, in milliseconds since 1 January 1970 UTC, that information was updated. | -| -- files | `Array[Object]`| Description and status of the files within the given granule. | -| -- name | `str` | The name and extension of the file. | -| -- cumulusArchiveLocation | `str` | Cumulus bucket the file resides in. | -| -- orcaArchiveLocation | `str` | ORCA S3 Glacier bucket the file resides in. | -| -- keyPath | `str` | S3 path to the file including the file name and extension, but not the bucket. | -| -- sizeBytes | `str` | Size in bytes of the file. From Cumulus ingest. | -| -- hash | `str` | Checksum hash of the file provided by Cumulus. | -| -- hashType | `str` | Hash type used to calculate the hash value of the file. | -| -- version | `str` | AWS provided version of the file. | +| providerId | `int` | The unique ID of the provider making the request. | +| collectionId | `str` | The unique ID of collection to compare. | +| id | `str` | The unique ID of the granule. | +| createdAt | `int` | The time, in milliseconds since 1 January 1970 UTC, data was originally ingested into cumulus. | +| executionId | `str` | Step function execution ID from AWS. | +| ingestDate | `int` | The time, in milliseconds since 1 January 1970 UTC, that the data was originally ingested into ORCA.| +| lastUpdate | `int` | The time, in milliseconds since 1 January 1970 UTC, that information was updated. | +| files | `Array[Object]`| Description and status of the files within the given granule. | +| name | `str` | The name and extension of the file. | +| cumulusArchiveLocation | `str` | Cumulus bucket the file resides in. | +| orcaArchiveLocation | `str` | ORCA S3 Glacier bucket the file resides in. | +| keyPath | `str` | S3 path to the file including the file name and extension, but not the bucket. | +| sizeBytes | `str` | Size in bytes of the file. From Cumulus ingest. | +| hash | `str` | Checksum hash of the file provided by Cumulus. | +| hashType | `str` | Hash type used to calculate the hash value of the file. | +| version | `str` | AWS provided version of the file. | The API returns status code 200 on success, 400 if `pageIndex` or `endTimestamp` is missing and 500 if an error occurs when querying the database. @@ -99,17 +100,18 @@ The `recovery/granules` API call relates to an ORCA recovery job status and retu Recovery granules API input invoke URL example: `https://example.execute-api.us-west-2.amazonaws.com/orca/recovery/granules` -### Catalog reporting API input +### Recovery granules API input An example of the API input body is shown below: ```json { - "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", + "granule_id": "MOD14A1.061.H5V12.2020312.141531789", "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85" } ``` The following table lists the fields in the input: + | Name | Data Type | Description | Required | -| ------------------| ----------- | -----------------------------------------------------------------------------------------|----------| +| ------------------|-------------|------------------------------------------------------------------------------------------|----------| | granule_id | `str` | The unique ID of the granule to retrieve status for. | Yes | | asyncOperationId | `str` | The unique ID of the asyncOperation. May apply to a request that covers multiple granules. | No | @@ -118,7 +120,7 @@ The following table lists the fields in the input: An example of the API output is shown below: ```json { - "granule_id": "6c8d0c8b-4f9a-4d87-ab7c-480b185a0250", + "granule_id": "MOD14A1.061.H5V12.2020312.141531789", "asyncOperationId": "43c9751b-9498-4733-90d8-56b1458e0f85", "files": [ { @@ -149,8 +151,8 @@ The following table lists the fields in the output: | granule_id | `str` | The unique ID of the granule retrieved. | | asyncOperationId | `str` | The unique ID of the asyncOperation. | | files | `Array[Object]`| Description and status of the files within the given granule. | -| -- file_name | `str` | The name and extension of the file. | -| -- status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | +| file_name | `str` | The name and extension of the file. | +| status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | | error_message | `str` | If the restoration of the file showed error, the error will be stored here. | | restore_destination | `str` | The name of the glacier bucket the granule is being copied to. | | request_time | `int` | The time, in milliseconds since 1 January 1970 UTC, when the request to restore the granule was initiated.| @@ -171,8 +173,9 @@ An example of the API input body is shown below: ``` The following table lists the fields in the input: + | Name | Data Type | Description | Required | -| ------------------| ----------- | ----------------------------------------------------------|-----------| +| ------------------| ------------| ----------------------------------------------------------|-----------| | asyncOperationId | `str` | The unique ID of the asyncOperation of the recovery job. | Yes | @@ -205,7 +208,7 @@ The following table lists the fields in the output: | asyncOperationId | `str` | The unique ID of the asyncOperation. | | job_status_totals | `Object` |Sum of how many granules are in each particular restoration status ('pending', 'staged', 'success', or 'failed').| | granules | `Array[Object]` | An array representing each granule being copied as part of the job. | -| -- granule_id | `str` | The unique ID of the granule retrieved. | -| -- status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | +| granule_id | `str` | The unique ID of the granule retrieved. | +| status | `str` | The status of the restoration of the file. May be 'pending', 'staged', 'success', or 'failed'. | The API returns status code 200 on success, 400 if `asyncOperationId` is missing, 500 if an error occurs when querying the database and 404 if not found. From 486a935b054407358e9a3d3bcd6763f14e49bdd1 Mon Sep 17 00:00:00 2001 From: Rizbi Hassan Date: Fri, 17 Dec 2021 10:13:08 -0600 Subject: [PATCH 7/7] forgot , --- website/docs/developer/api/api-gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/developer/api/api-gateway.md b/website/docs/developer/api/api-gateway.md index 2b21f25a9..5d0fab312 100644 --- a/website/docs/developer/api/api-gateway.md +++ b/website/docs/developer/api/api-gateway.md @@ -59,7 +59,7 @@ An example of the API output is shown below: "orcaArchiveLocation": "orca-archive", "keyPath": "MOD14A1/061/032/MOD14A1.061.A23V45.2020235.2020240145621.hdf", "sizeBytes": 100934568723, - "hash": "ACFH325128030192834127347" + "hash": "ACFH325128030192834127347", "hashType": "SHA-256", "version": "VXCDEG902" }