Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for change notification #1267

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add documentation for change notification #1267

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
82299e5
Add documentation for change notification
qtomlinson Jan 9, 2025
d4b4aa6
Merge branch 'master' into qt/doc_change_notification
qtomlinson Jan 10, 2025
1083e03
Merge branch 'master' into qt/doc_change_notification
qtomlinson Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/change-notification-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.


### 1. Get List of Changeset File Names

- **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:**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Example Response:**
- **Example Response:** (_Partial response shown. The real response will include the list of all changesets from 2019 to now_)

```
2019-04-01-01
2019-02-07-23
Comment on lines +11 to +12
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this should show the list in order. It is always in time ascending order.

Suggested change
2019-04-01-01
2019-02-07-23
2019-02-08-03
2019-02-08-04

```

### 2. Get Specific Changeset

- **Endpoint:** `GET {{baseurl}}/changes/{changeset}`
- **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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

```
- **Example Response:**
```
composer/packagist/alibabacloud/dysmsapi-20170525/1.0.0.json
composer/packagist/alibabacloud/dysmsapi-20170525/1.0.2.json
Comment on lines +25 to +26
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The suggested changeset 2019-02-08-04 has only two coordinates and they are...

Suggested change
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?

```

### 3. Get Changed Definition

- **Endpoint:** `GET {{baseurl}}/{coordinates}.json`
- **Description:** Retrieves the changed definition without including files.
- **Example Request:**
```
GET {{baseurl}}/composer/packagist/alibabacloud/dysmsapi-20170525/1.0.0.json
```

**Base URL for Test Data:** https://clearlydefineddev.blob.core.windows.net/develop-snapshots
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Loading