CMR-10257: [Fix] Updating API Docs to simplify language #2195
Conversation
jmaeng72
changed the title
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2195 +/- ##
=======================================
Coverage 58.23% 58.23%
=======================================
Files 1056 1056
Lines 71009 71009
Branches 2025 2023 -2
=======================================
Hits 41351 41351
- Misses 27768 27769 +1
+ Partials 1890 1889 -1 ☔ View full report in Codecov by Sentry. 🚨 Try these New Features:
|
ingest-app/docs/api.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
Rather than describe the subscription types as "search" and "ingest" we should give a more user-facing description. Something like: "batch notification" and "near-real-time notification".
ingest-app/docs/api.md
Outdated
|
|
||
| Subscription concepts can be created by sending an HTTP POST or PUT with the metadata sent as data to the URL `%CMR-ENDPOINT%/subscriptions/<native-id>`. 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. |
There was a problem hiding this comment.
sent out via the provided notification endpoint, such as an AWS SQS messaging queue.
ingest-app/docs/api.md
Outdated
|
|
||
| `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): |
There was a problem hiding this comment.
Batch subscription processing is run periodically and execute CMR search queries, as defined by the Subscription definition, and notify users ...
There was a problem hiding this comment.
...two types of batch process subscriptions...
ingest-app/docs/api.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Batch subscription notification processing is executed periodically...
Notification of updates is via the email address associated with the SubscriberId's EarthData Login (URS).
There was a problem hiding this comment.
I do see that the parameter description section describes this but if feels like a good thing to mention as an overview also, since that is the notification mechanism.
ingest-app/docs/api.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Note: this is not configurable by the client, so no need to include it in the API docs
ingest-app/docs/api.md
Outdated
| - `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 |
There was a problem hiding this comment.
...for Near Real-time Subscriptions
Basically, rename "Ingest subscription" everywhere to NRT or whatever we land on.
search-app/docs/api.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
similar comments for the search doc, replace "ingest subscriptions" and "search subscriptions"
Overview
What is the feature/fix?
After review of API docs for new subscription api changes, there needed to be more simplification and clarification to them
What is the Solution?
Organized information for easier understanding
What areas of the application does this impact?
Ingest and Search API Docs
Checklist