Add documentation for change notification #1267
Conversation
| @@ -0,0 +1,38 @@ | |||
| ## Change Notification API Calls | |||
|
|
|||
| The system includes a built-in mechanism to [support notifications for definition changes](https://github.com/clearlydefined/service/issues/958). Changes in definitions, excluding files, and their associated coordinates are published at regular intervals. Every hour, a changeset file is released, listing the coordinates of definitions that have changed during that time. You can retrieve these updated definitions (excluding files) using the appropriate API. This document explains how to use the APIs designed to support change notifications. | |||
There was a problem hiding this comment.
| The system includes a built-in mechanism to [support notifications for definition changes](https://github.com/clearlydefined/service/issues/958). Changes in definitions, excluding files, and their associated coordinates are published at regular intervals. Every hour, a changeset file is released, listing the coordinates of definitions that have changed during that time. You can retrieve these updated definitions (excluding files) using the appropriate API. This document explains how to use the APIs designed to support change notifications. | |
| The system includes a built-in mechanism to [support notifications for definition changes](https://github.com/clearlydefined/service/issues/958). Changes in definitions, excluding files, and their associated coordinates are published at regular intervals. Every hour, a changeset file is released, listing the coordinates of definitions that have changed during the last hour. You can retrieve these updated definitions (excluding files) using the appropriate API. This document explains how to use the APIs designed to support change notifications. |
| 2019-04-01-01 | ||
| 2019-02-07-23 |
There was a problem hiding this comment.
I wonder if this should show the list in order. It is always in time ascending order.
| 2019-04-01-01 | |
| 2019-02-07-23 | |
| 2019-02-08-03 | |
| 2019-02-08-04 |
|
|
||
| - **Endpoint:** `GET {{baseurl}}/changes/index` | ||
| - **Description:** Retrieves a list of changeset file names. These files are published hourly and follow the naming convention `yyyy-mm-dd-hh`. | ||
| - **Example Response:** |
There was a problem hiding this comment.
| - **Example Response:** | |
| - **Example Response:** (_Partial response shown. The real response will include the list of all changesets from 2019 to now_) |
| - **Description:** Retrieves a specific changeset containing the coordinates of definitions that have been changed during the specified hourly interval. | ||
| - **Example Request:** | ||
| ``` | ||
| GET {{baseurl}}/changes/2019-02-07-23 |
There was a problem hiding this comment.
Ideally this would be a valid changeset in both dev and prod. The earliest changeset for production is 2019-04-01-16. But the changesets in develop-snapshots are all for 2019-02. I'm not sure why there wouldn't be overlap.
The index for dev goes between 2019-02 and 2023-10. If we copied over a changeset and some definitions in that changeset from early 2023, we could have overlapping examples that work in both dev and prod.
| GET {{baseurl}}/changes/2019-02-07-23 | |
| GET {{baseurl}}/changes/2019-02-08-04 |
Doesn't look like it is easy to copy a blob from one container to another.
| composer/packagist/alibabacloud/dysmsapi-20170525/1.0.0.json | ||
| composer/packagist/alibabacloud/dysmsapi-20170525/1.0.2.json |
There was a problem hiding this comment.
The suggested changeset 2019-02-08-04 has only two coordinates and they are...
| composer/packagist/alibabacloud/dysmsapi-20170525/1.0.0.json | |
| composer/packagist/alibabacloud/dysmsapi-20170525/1.0.2.json | |
| composer/packagist/ccxt/ccxt/1.21.52.json | |
| composer/packagist/ccxt/ccxt/1.21.50.json |
This changeset does not exist in production, so the example will only match when they use the dev baseurl.
I suppose we could give two examples. One for dev and one for prod. What do you think?
| GET {{baseurl}}/composer/packagist/alibabacloud/dysmsapi-20170525/1.0.0.json | ||
| ``` | ||
|
|
||
| **Base URL for Test Data:** https://clearlydefineddev.blob.core.windows.net/develop-snapshots |
There was a problem hiding this comment.
Should we include the production baseurl? The base URL has the actual Azure path. We probably want to have an alias if it is published external. That way if the Azure path changes, the public endpoint will be the same.
BTW... I confirmed that both are READONLY.
|
I really like the format you used for this with the descriptions and examples for each endpoint. This will be very helpful. |
No description provided.