From d50a3cb0b85b5eae0aa7ce66765ada40416cf802 Mon Sep 17 00:00:00 2001 From: jmaeng72 <44305062+jmaeng72@users.noreply.github.com> Date: Wed, 20 Nov 2024 13:52:21 -0500 Subject: [PATCH 1/5] update api docs fo ingest app --- ingest-app/docs/api.md | 146 +++++++++++++++++++++++++++++------------ 1 file changed, 104 insertions(+), 42 deletions(-) diff --git a/ingest-app/docs/api.md b/ingest-app/docs/api.md index 0f934c2187..7786a37241 100644 --- a/ingest-app/docs/api.md +++ b/ingest-app/docs/api.md @@ -1081,47 +1081,38 @@ Tool metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT #### Successful Response in JSON {"concept-id":"TL1200000015-PROV1","revision-id":2} -## Subscription -### Create a Subscription -#### /subscriptions - -NOTE: The `%CMR-ENDPOINT%/providers//subscriptions` API routes for subscription ingest are deprecated. Please switch to the new `%CMR-ENDPOINT%/subscriptions` API routes. All the examples below are using the new routes. - -Subscription allows a user to register some query conditions in the CMR and be notified when collections/granules matching the conditions are created, updated, or deleted in the CMR. By the end of 2024 there are two kinds of subscriptions. Those that are run by search queries and those that are processed on ingest. The ingest subscriptions are only for granules and notifications are sent out to a provided AWS SQS endpoint. The search subscriptions are run periodically using CMR search and notifiy users by email using the email address that is registered in Earthdata Login. For the search subscriptions, there are two types of subscriptions (identified by the `Type` field of the subscription): -- collection subscription for users to be notified when collections are created/updated. -- granule subscription for users to be notified when granules are created/updated. +## Subscriptions +A subscription allows a user to be notified when specific collections/granules are created, updated, or deleted. The collections/granules specified can be filtered by query conditions. -Subscription metadata is in JSON format and conforms to [UMM-Sub Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/subscription). There is a background job that processes the search subscriptions periodically (configurable), to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. +There are two kinds of subscriptions: Search and Ingest -Subscription concepts can be created by sending an HTTP POST or PUT with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/`. The response will include the [concept id](#concept-id) ,the [revision id](#revision-id), and a [native-id](#native-id). +- Ingest subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out to a provided AWS SQS endpoint. -`Type` is a required field in subscription request body. The valid values of `Type` are: `"collection"` or `"granule"`. It indicates if the subscription is a collection subscription or granule subscription. Subscriptions of type granule must supply a requisite CollectionConceptId, and subscriptions of type collection cannot have a CollectionConceptId field. When the CollectionConceptId field is used, the subscription subscriber must have read access to the collection, otherwise the ingest of the subscription will fail. +- Search subscriptions run periodically via CMR search queries and notify users by the email address that is registered in Earthdata Login. There are two types of subscriptions (identified by the `Type` field of the subscription): -If a native-id is not provided it will be generated. This is only supported for POST requests. -POST requests may only be used for creating subscriptions. + - collection subscription for users to be notified when collections are created/updated. + - granule subscription for users to be notified when granules are created/updated. -If a SubscriberId is not provided, then the user ID associated with the token used to ingest the subscription will be used as the SubscriberId. +There is a configurable background job that processes the search subscriptions periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. -EmailAddress was previously a required field, but this field is now deprecated. Instead, the email address associated with the SubscriberId's EarthData Login (URS) account will be used as the EmailAddress. If an EmailAddress is specified at subscription creation it will be ignored. - -For ingest subscriptions to be used there are three new fields that are requird in addition to the other fields already described. First though, the Type field must be set to `granule` as ingest subscriptions are only for granules. Because this is a granule subscription the CollectionConceptId must be set. The new fields are: +### Create a Subscription +#### /subscriptions -Method is a new field and it designates between search subscriptions and ingest subscriptions. Thus the valid values for this field are either `search` or `ingest`. If this field is not used, then search is assumed. +NOTE: The `%CMR-ENDPOINT%/providers//subscriptions` API routes for subscription ingest are deprecated. Please switch to the new `%CMR-ENDPOINT%/subscriptions` API routes. All the examples below are using the new routes. -EndPoint describes to where notifications get sent. At this time only Amazon Web Services (AWS) Simple Query Service (SQS) Amazon Resource Names (ARN) are allowed. Ingest of subscriptions that do not use an AWS SQS ARN will fail. If search subscriptions are desired, do not use this field. +##### Method Options +Subscription concepts can be created by sending an HTTP POST or PUT with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/`. -Mode describes whether the notification is for New (ingested for the first time into the CMR) granules, Updated granules, or Deleted granules. The valid values are New, Update, Delete. Any combination of these values are valid and they are set using a json array. Here are some examples: - [`New`] - [`New`, `Update`] - [`Update`, `Delete`] - [`Update`] +The response will include the [concept id](#concept-id) ,the [revision id](#revision-id), and a [native-id](#native-id). -POST only may be used without a native-id at the following URL. -`%CMR-ENDPOINT%/subscriptions` +- POST or PUT may be used with the following URL: `%CMR-ENDPOINT%/subscriptions/` +- When using POST: + - May only be used for creating subscriptions + - Can use without a native-id at the following URL: `%CMR-ENDPOINT%/subscriptions` + - The native-id will be auto-generated -POST or PUT may be used with the following URL. -`%CMR-ENDPOINT%/subscriptions/` +##### Query Params for Search Subscriptions Query values are currently only for search subscriptions and should not be URL encoded. Instead, the query should consist of standard granule search parameters, separated by '&'. For example, a valid query string might look like: @@ -1129,19 +1120,75 @@ Query values are currently only for search subscriptions and should not be URL e If the query provided is invalid for granule searching, subscription creation will fail with HTTP status response of 400, and an error message detailing which query parameters were invalid. -### Update a Subscription -#### /subscriptions/<native-id> -Subscription concept can be updated by sending an HTTP POST or PUT with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). -If a native-id is provided in a POST, and a subscription already exists for that provider with the given native-id, the request will be rejected. +##### Data Fields +The metadata sent in the body of the request is in JSON format and conforms to [UMM-Sub Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/subscription). This metadata data body consists of specific fields below: + +- `Name`: [required] Name of subscription +- `Type`: [required] Indicates if the subscription is a collection subscription or granule subscription. + - Valid values: `"collection"`,`"granule"`. + - "Type": "granule": must supply a requisite CollectionConceptId field. The subscriber must have read access to the collection here, or the subscription will fail. + - "Type": "collection": cannot have a CollectionConceptId field. +- `Method`: [required] designates between search subscriptions and ingest subscriptions + - Valid values: `search` or `ingest`. + - Default: `search` +- `SubscriberId`: [optional] If a SubscriberId is not provided, then the user ID associated with the token used to ingest the subscription will be used as the SubscriberId. +- `EmailAddress`: [deprecated] was previously a required field, but is now deprecated. Instead, the email address associated with the SubscriberId's EarthData Login (URS) account will be used as the EmailAddress. If an EmailAddress is specified at subscription creation it will be ignored. +- `MetadataSpecification`: [required] Specifies which metadata version schema you are using for this subscription. Currently, that version is 1.1.1. + +##### Additional Data Fields for Ingest Subscriptions +For ingest subscriptions to be used there are three new fields that are required in addition to the other fields already described. +- `Type`: [required] Must be set to `granule` because ingest subscriptions are only for granules. +- `CollectionConceptId`: [required] Because type must be `granule`, we must set `CollectionConceptId` as well, as indicated in Data Fields section +- `EndPoint`: describes where notifications get sent. At this time only AWS SQS ARN's are allowed. Ingest subscriptions that do not use an AWS SQS ARN will fail. If search subscriptions are desired, do not use this field. +- `Mode`: describes whether the notification is for New (ingested for the first time into the CMR) granules, Updated granules, or Deleted granules. + - Valid values: `New`, `Update`, `Delete`. Any combination of these values are valid and they are set using a json array. + - Examples: + [`New`] or + [`New`, `Update`] or + [`Update`, `Delete`] or + [`Update`] + +##### Ingest Subscription POST Request + +``` +curl --request POST '%CMR-ENDPOINT%/ingest/subscriptions/my-native-id-of-my-subscription' \ +--header 'Content-Type: application/vnd.nasa.cmr.umm+json' \ +--header 'Authorization: ••••••' \ +--data-raw '{ + "Name": "Ingest-Subscription-Test", + "Type": "granule", + "SubscriberId": "My_sub_id", + "EmailAddress": "myemail@email.com", + "CollectionConceptId": "MyCollectionID", + "EndPoint": "MyAWSSQSARN", + "Mode": ["New","Update"], + "Method":"ingest", + "MetadataSpecification": { + "URL": "https://cdn.earthdata.nasa.gov/umm/subscription/v1.1.1", + "Name": "UMM-Sub", + "Version": "1.1.1" + } +} +' +``` -PUT requests should be used for updating subscriptions. Creation of subscriptions using PUT may be deprecated in the future. All PUT requests require a native-id to be part of the request URL. -Following are two examples that show how to update and create a search subscription. The third example shows how to create an ingest subscription using PUT. +##### Ingest Subscription Successful Response in XML ``` -curl -XPUT \ + + + SUB12345678-MyCollectionID + my-native-id-of-my-subscription + 1 + +``` + +##### Create search subscription with %CMR-ENDPOINT%/subscriptions URL (native-id will be autogenerated) +``` +curl -XPOST \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ -H "Authorization: XXXX" \ - %CMR-ENDPOINT%/subscriptions/subscription123 \ + %CMR-ENDPOINT%/subscriptions \ -d \ "{\"Name\": \"someSubscription\", \"Type\": \"granule\", @@ -1150,11 +1197,23 @@ curl -XPUT \ \"Query\": \"polygon=-18,-78,-13,-74,-16,-73,-22,-77,-18,-78\"}" ``` + +### Update a Subscription +#### /subscriptions/<native-id> +Subscription concept can be updated by sending an HTTP POST or PUT request with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/`. + +The response will include the [concept id](#concept-id) ,the [revision id](#revision-id), and a [native-id](#native-id). + +If a native-id is provided in a POST, and a subscription already exists for that provider with the given native-id, the request will be rejected. + +PUT requests should be used for updating subscriptions. Creating subscriptions with PUT may be deprecated in the future. All PUT requests require a native-id to be part of the request URL. + +##### Create search subscription with %CMR-ENDPOINT%/subscriptions/ URL ``` -curl -XPOST \ +curl -XPUT \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ -H "Authorization: XXXX" \ - %CMR-ENDPOINT%/subscriptions \ + %CMR-ENDPOINT%/subscriptions/subscription123 \ -d \ "{\"Name\": \"someSubscription\", \"Type\": \"granule\", @@ -1163,6 +1222,7 @@ curl -XPOST \ \"Query\": \"polygon=-18,-78,-13,-74,-16,-73,-22,-77,-18,-78\"}" ``` +##### Update ingest subscription with PUT ``` curl -XPUT \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ @@ -1188,7 +1248,7 @@ curl -XPUT \ SUB1200000015-PROV1 - 1 + 2 subscription123 ``` @@ -1197,11 +1257,13 @@ curl -XPUT \ By passing the option `-H "Accept: application/json"` to `curl`, one may get a JSON response: - {"concept-id":"SUB1200000015-PROV1","revision-id":1,"native-id":"subscription123"} + {"concept-id":"SUB1200000015-PROV1","revision-id":2,"native-id":"subscription123"} ### Delete a Subscription -Subscription metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/subscriptions/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. +Subscription metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/subscriptions/`. + +The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. ``` curl -XDELETE \ From 327e6829500e58d782adb733e38e53a525365fac Mon Sep 17 00:00:00 2001 From: jmaeng72 <44305062+jmaeng72@users.noreply.github.com> Date: Wed, 20 Nov 2024 13:59:05 -0500 Subject: [PATCH 2/5] update search api --- search-app/docs/api.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/search-app/docs/api.md b/search-app/docs/api.md index a8b067b706..57f094a29d 100644 --- a/search-app/docs/api.md +++ b/search-app/docs/api.md @@ -5122,12 +5122,18 @@ On occasions when tool dissociation cannot be processed at all due to invalid in ### Subscription -Subscription allows a user to register some query conditions in the CMR and be notified when collections/granules matching the conditions are created, updated, or deleted in the CMR. By the end of 2024 there are two kinds of subscriptions. Those that are run by search queries and those that are processed on ingest. The ingest subscriptions are only for granules and notifications are sent out to a provided AWS SQS endpoint. The search subscriptions are run periodically using CMR search and notifiy users by email using the email address that is registered in Earthdata Login. For the search subscriptions, there are two types of subscriptions (identified by the `Type` field of the subscription): +A subscription allows a user to be notified when specific collections/granules are created, updated, or deleted. The collections/granules specified can be filtered by query conditions. -- collection subscription for users to be notified when collections are created/updated. -- granule subscription for users to be notified when granules are created/updated. +There are two kinds of subscriptions: Search and Ingest -Subscription metadata is in JSON format and conforms to [UMM-Sub Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/subscription). Subscriptions of type `granule` must supply a requisite CollectionConceptId, and subscriptions of type `collection` cannot have a CollectionConceptId field. There is a background job that processes the search subscriptions periodically (configurable), to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. +- Ingest subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out to a provided AWS SQS endpoint. + +- Search subscriptions run periodically via CMR search queries and notify users by the email address that is registered in Earthdata Login. There are two types of subscriptions (identified by the `Type` field of the subscription): + + - collection subscription for users to be notified when collections are created/updated. + - granule subscription for users to be notified when granules are created/updated. + +There is a configurable background job that processes the search subscriptions periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. #### Searching for Subscriptions From 247205cd3fb594f350f40e7e27805d0857ca4acf Mon Sep 17 00:00:00 2001 From: jmaeng72 <44305062+jmaeng72@users.noreply.github.com> Date: Thu, 21 Nov 2024 09:58:39 -0500 Subject: [PATCH 3/5] rename subscriptions and reword some phrases --- ingest-app/docs/api.md | 30 +++++++++++++++--------------- search-app/docs/api.md | 12 ++++++------ 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/ingest-app/docs/api.md b/ingest-app/docs/api.md index 7786a37241..51a5dd7c61 100644 --- a/ingest-app/docs/api.md +++ b/ingest-app/docs/api.md @@ -1085,16 +1085,16 @@ Tool metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT ## Subscriptions A subscription allows a user to be notified when specific collections/granules are created, updated, or deleted. The collections/granules specified can be filtered by query conditions. -There are two kinds of subscriptions: Search and Ingest +There are two kinds of subscriptions: Batch Notification and Near-Real-Time Notification -- Ingest subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out to a provided AWS SQS endpoint. +- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. -- Search subscriptions run periodically via CMR search queries and notify users by the email address that is registered in Earthdata Login. There are two types of subscriptions (identified by the `Type` field of the subscription): +- Batch Notification subscription processing is run periodically and execute CMR search queries, as defined by the subscription definition, and notify users by the email address that is registered in Earthdata Login. There are two types of batch process subscriptions (identified by the `Type` field of the subscription): - - collection subscription for users to be notified when collections are created/updated. - - granule subscription for users to be notified when granules are created/updated. + - collection subscription for users to be notified when collections are created/updated, or + - granule subscription for users to be notified when granules are created/updated -There is a configurable background job that processes the search subscriptions periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. +Batch subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). ### Create a Subscription #### /subscriptions @@ -1112,7 +1112,7 @@ The response will include the [concept id](#concept-id) ,the [revision id](#revi - Can use without a native-id at the following URL: `%CMR-ENDPOINT%/subscriptions` - The native-id will be auto-generated -##### Query Params for Search Subscriptions +##### Query Params for Batch Notification Subscriptions Query values are currently only for search subscriptions and should not be URL encoded. Instead, the query should consist of standard granule search parameters, separated by '&'. For example, a valid query string might look like: @@ -1136,12 +1136,12 @@ The metadata sent in the body of the request is in JSON format and conforms to [ - `EmailAddress`: [deprecated] was previously a required field, but is now deprecated. Instead, the email address associated with the SubscriberId's EarthData Login (URS) account will be used as the EmailAddress. If an EmailAddress is specified at subscription creation it will be ignored. - `MetadataSpecification`: [required] Specifies which metadata version schema you are using for this subscription. Currently, that version is 1.1.1. -##### Additional Data Fields for Ingest Subscriptions +##### Additional Data Fields for Near-Real-Time Notification Subscriptions For ingest subscriptions to be used there are three new fields that are required in addition to the other fields already described. - `Type`: [required] Must be set to `granule` because ingest subscriptions are only for granules. - `CollectionConceptId`: [required] Because type must be `granule`, we must set `CollectionConceptId` as well, as indicated in Data Fields section -- `EndPoint`: describes where notifications get sent. At this time only AWS SQS ARN's are allowed. Ingest subscriptions that do not use an AWS SQS ARN will fail. If search subscriptions are desired, do not use this field. -- `Mode`: describes whether the notification is for New (ingested for the first time into the CMR) granules, Updated granules, or Deleted granules. +- `EndPoint`: [required] describes where notifications get sent. At this time only AWS SQS ARN's are allowed. Ingest subscriptions that do not use an AWS SQS ARN will fail. If search subscriptions are desired, do not use this field. +- `Mode`: [required] describes whether the notification is for New (ingested for the first time into the CMR) granules, Updated granules, or Deleted granules. - Valid values: `New`, `Update`, `Delete`. Any combination of these values are valid and they are set using a json array. - Examples: [`New`] or @@ -1149,7 +1149,7 @@ For ingest subscriptions to be used there are three new fields that are required [`Update`, `Delete`] or [`Update`] -##### Ingest Subscription POST Request +##### NRT Notification Subscription POST Request ``` curl --request POST '%CMR-ENDPOINT%/ingest/subscriptions/my-native-id-of-my-subscription' \ @@ -1173,7 +1173,7 @@ curl --request POST '%CMR-ENDPOINT%/ingest/subscriptions/my-native-id-of-my-sub ' ``` -##### Ingest Subscription Successful Response in XML +##### NRT Notification Subscription Successful Response in XML ``` @@ -1183,7 +1183,7 @@ curl --request POST '%CMR-ENDPOINT%/ingest/subscriptions/my-native-id-of-my-sub ``` -##### Create search subscription with %CMR-ENDPOINT%/subscriptions URL (native-id will be autogenerated) +##### Create Batch Notification subscription with %CMR-ENDPOINT%/subscriptions URL (native-id will be autogenerated) ``` curl -XPOST \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ @@ -1208,7 +1208,7 @@ If a native-id is provided in a POST, and a subscription already exists for that PUT requests should be used for updating subscriptions. Creating subscriptions with PUT may be deprecated in the future. All PUT requests require a native-id to be part of the request URL. -##### Create search subscription with %CMR-ENDPOINT%/subscriptions/ URL +##### Create Batch Notification subscription with %CMR-ENDPOINT%/subscriptions/ URL ``` curl -XPUT \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ @@ -1222,7 +1222,7 @@ curl -XPUT \ \"Query\": \"polygon=-18,-78,-13,-74,-16,-73,-22,-77,-18,-78\"}" ``` -##### Update ingest subscription with PUT +##### Update NRT Notification subscription with PUT ``` curl -XPUT \ -H "Content-type: application/vnd.nasa.cmr.umm+json" \ diff --git a/search-app/docs/api.md b/search-app/docs/api.md index 57f094a29d..e5e5e7d951 100644 --- a/search-app/docs/api.md +++ b/search-app/docs/api.md @@ -5124,16 +5124,16 @@ On occasions when tool dissociation cannot be processed at all due to invalid in A subscription allows a user to be notified when specific collections/granules are created, updated, or deleted. The collections/granules specified can be filtered by query conditions. -There are two kinds of subscriptions: Search and Ingest +There are two kinds of subscriptions: Batch Notification and Near-Real-Time Notification -- Ingest subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out to a provided AWS SQS endpoint. +- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. -- Search subscriptions run periodically via CMR search queries and notify users by the email address that is registered in Earthdata Login. There are two types of subscriptions (identified by the `Type` field of the subscription): +- Batch Notification subscription processing is run periodically and execute CMR search queries, as defined by the subscription definition, and notify users by the email address that is registered in Earthdata Login. There are two types of batch process subscriptions (identified by the `Type` field of the subscription): - - collection subscription for users to be notified when collections are created/updated. - - granule subscription for users to be notified when granules are created/updated. + - collection subscription for users to be notified when collections are created/updated, or + - granule subscription for users to be notified when granules are created/updated -There is a configurable background job that processes the search subscriptions periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and notify the subscription user with any matches. +Batch subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). #### Searching for Subscriptions From a12101f3b8a141a3f1de88798b22caddeb46cbb1 Mon Sep 17 00:00:00 2001 From: jmaeng72 <44305062+jmaeng72@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:05:48 -0500 Subject: [PATCH 4/5] update search and ingest to nrt and batch notification --- ingest-app/docs/api.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ingest-app/docs/api.md b/ingest-app/docs/api.md index 51a5dd7c61..a9643a0649 100644 --- a/ingest-app/docs/api.md +++ b/ingest-app/docs/api.md @@ -1099,7 +1099,7 @@ Batch subscription notification processing is executed periodically, to see if t ### Create a Subscription #### /subscriptions -NOTE: The `%CMR-ENDPOINT%/providers//subscriptions` API routes for subscription ingest are deprecated. Please switch to the new `%CMR-ENDPOINT%/subscriptions` API routes. All the examples below are using the new routes. +NOTE: The `%CMR-ENDPOINT%/providers//subscriptions` API routes for subscriptions are deprecated. Please switch to the new `%CMR-ENDPOINT%/subscriptions` API routes. All the examples below are using the new routes. ##### Method Options Subscription concepts can be created by sending an HTTP POST or PUT with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/`. @@ -1114,7 +1114,7 @@ The response will include the [concept id](#concept-id) ,the [revision id](#revi ##### Query Params for Batch Notification Subscriptions -Query values are currently only for search subscriptions and should not be URL encoded. Instead, the query should consist of standard granule search parameters, separated by '&'. For example, a valid query string might look like: +Query values are currently only for Batch Notification subscriptions and should not be URL encoded. Instead, the query should consist of standard granule search parameters, separated by '&'. For example, a valid query string might look like: instrument=MODIS&sensor=1B&polygon=-18,-78,-13,-74,-16,-73,-22,-77,-18,-78 @@ -1129,7 +1129,7 @@ The metadata sent in the body of the request is in JSON format and conforms to [ - Valid values: `"collection"`,`"granule"`. - "Type": "granule": must supply a requisite CollectionConceptId field. The subscriber must have read access to the collection here, or the subscription will fail. - "Type": "collection": cannot have a CollectionConceptId field. -- `Method`: [required] designates between search subscriptions and ingest subscriptions +- `Method`: [required] designates between search (Batch Notification) subscriptions and ingest (Near-Real-Time) subscriptions - Valid values: `search` or `ingest`. - Default: `search` - `SubscriberId`: [optional] If a SubscriberId is not provided, then the user ID associated with the token used to ingest the subscription will be used as the SubscriberId. @@ -1137,10 +1137,10 @@ The metadata sent in the body of the request is in JSON format and conforms to [ - `MetadataSpecification`: [required] Specifies which metadata version schema you are using for this subscription. Currently, that version is 1.1.1. ##### Additional Data Fields for Near-Real-Time Notification Subscriptions -For ingest subscriptions to be used there are three new fields that are required in addition to the other fields already described. -- `Type`: [required] Must be set to `granule` because ingest subscriptions are only for granules. +For NRT Notification subscriptions to be used there are three new fields that are required in addition to the other fields already described. +- `Type`: [required] Must be set to `granule` because NRT Notification subscriptions are only for granules. - `CollectionConceptId`: [required] Because type must be `granule`, we must set `CollectionConceptId` as well, as indicated in Data Fields section -- `EndPoint`: [required] describes where notifications get sent. At this time only AWS SQS ARN's are allowed. Ingest subscriptions that do not use an AWS SQS ARN will fail. If search subscriptions are desired, do not use this field. +- `EndPoint`: [required] describes where notifications get sent. At this time only AWS SQS ARN's are allowed. NRT Notification subscriptions that do not use an AWS SQS ARN will fail. If Batch Notification subscriptions are desired, do not use this field. - `Mode`: [required] describes whether the notification is for New (ingested for the first time into the CMR) granules, Updated granules, or Deleted granules. - Valid values: `New`, `Update`, `Delete`. Any combination of these values are valid and they are set using a json array. - Examples: @@ -1261,7 +1261,7 @@ get a JSON response: ### Delete a Subscription -Subscription metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/subscriptions/`. +Subscriptions can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/subscriptions/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. From 1e9727aa223fad760175e9c72f1a95c3ef18cf15 Mon Sep 17 00:00:00 2001 From: jmaeng72 <44305062+jmaeng72@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:09:02 -0500 Subject: [PATCH 5/5] re-order sub types desc --- ingest-app/docs/api.md | 11 ++++++----- search-app/docs/api.md | 10 +++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/ingest-app/docs/api.md b/ingest-app/docs/api.md index a9643a0649..af91efe3ee 100644 --- a/ingest-app/docs/api.md +++ b/ingest-app/docs/api.md @@ -1087,14 +1087,15 @@ A subscription allows a user to be notified when specific collections/granules a There are two kinds of subscriptions: Batch Notification and Near-Real-Time Notification -- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. - -- Batch Notification subscription processing is run periodically and execute CMR search queries, as defined by the subscription definition, and notify users by the email address that is registered in Earthdata Login. There are two types of batch process subscriptions (identified by the `Type` field of the subscription): +- Batch Notification subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). + There are two types of batch process subscriptions (identified by the `Type` field of the subscription): - collection subscription for users to be notified when collections are created/updated, or - - granule subscription for users to be notified when granules are created/updated + - granule subscription for users to be notified when granules are created/update + + +- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. -Batch subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). ### Create a Subscription #### /subscriptions diff --git a/search-app/docs/api.md b/search-app/docs/api.md index e5e5e7d951..d5063f39a0 100644 --- a/search-app/docs/api.md +++ b/search-app/docs/api.md @@ -5126,14 +5126,14 @@ A subscription allows a user to be notified when specific collections/granules a There are two kinds of subscriptions: Batch Notification and Near-Real-Time Notification -- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. - -- Batch Notification subscription processing is run periodically and execute CMR search queries, as defined by the subscription definition, and notify users by the email address that is registered in Earthdata Login. There are two types of batch process subscriptions (identified by the `Type` field of the subscription): +- Batch Notification subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). + There are two types of batch process subscriptions (identified by the `Type` field of the subscription): - collection subscription for users to be notified when collections are created/updated, or - - granule subscription for users to be notified when granules are created/updated + - granule subscription for users to be notified when granules are created/update -Batch subscription notification processing is executed periodically, to see if there are any collections/granules that are created/updated since the last time the subscription has been processed and will notify the subscription user with any matches. Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS). + +- Near-Real-Time (NRT) Notification subscriptions are processed on ingest and are only for granules. When a user subscribes, notifications are sent out via the provided notification endpoint, such as an AWS SQS messaging queue. #### Searching for Subscriptions