diff --git a/content/api/collection.md b/content/api/collection.md index f6cdcd4d..5d052343 100644 --- a/content/api/collection.md +++ b/content/api/collection.md @@ -7,7 +7,7 @@ weight: 2 As Open Terms Archive is decentralised, each instance embarks its own API. The documentation relevant to the specific version of the engine on that instance is provided on that instance itself. -The Collection API exposes JSON data over HTTP. Its [OpenAPI](https://swagger.io/specification/) specification can be found at `http://localhost:///docs`. +The Collection API exposes data over HTTP: versioning data in JSON format and [Atom feeds]({{< relref "/terms/how-to/be-notified" >}}) for subscription. Its [OpenAPI](https://swagger.io/specification/) specification can be found at `http://localhost:///docs`. That endpoint exposes both the OpenAPI specification if the requested `Content-Type` is JSON, and a Swagger UI for visual and interactive documentation otherwise. diff --git a/content/collections/reference/configuration.md b/content/collections/reference/configuration.md index 39e5916d..933fab33 100644 --- a/content/collections/reference/configuration.md +++ b/content/collections/reference/configuration.md @@ -246,6 +246,13 @@ The collection API section sets the parameters for the API server. required=true />}} +{{< refItem + name="collection-api.feed.limit" + type="number" + description="Maximum number of entries returned by feed endpoints." + default="100" +/>}} + --- ## Storage Repositories diff --git a/content/terms/how-to/be-notified.md b/content/terms/how-to/be-notified.md index 417f18e5..38ba3143 100644 --- a/content/terms/how-to/be-notified.md +++ b/content/terms/how-to/be-notified.md @@ -9,35 +9,26 @@ aliases: # How to be notified of terms changes -An RSS feed is a type of web page that contains information about the latest content published by a website, such as the date of publication and the address where you can view it. When this resource is updated, a feed reader app automatically notifies you and you can see the update. You can receive notification for a specific service or document by subscribing to RSS feeds. +An Atom feed is a type of web page that contains information about the latest content published by a website, such as the date of publication and the address where you can view it. When this resource is updated, a feed reader app automatically notifies you and you can see the update. You can receive notification for a specific service or terms type by subscribing to Atom feeds. -- - - +Each collection exposes Atom feeds through its [Collection API]({{< relref "/api/collection" >}}). The endpoint of a collection's API can be found in the [collections list](https://opentermsarchive.org/collections.json) under the `endpoint` property. -## For specific terms - -To find out the address of the RSS feed you want to subscribe to: +## For all terms of a collection -1. [Navigate]({{< relref "/analysis/how-to/navigate-history" >}}) to the page with the history of changes you are interested in. - - For example, for the GitHub Privacy Policy of the Demo collection, this would be [this page](https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md). -2. Copy the address of that page from your browser’s address bar. - - In the address, if they are present, replace the words `blob` or `tree` with `commits`. - - For example, for the GitHub Privacy Policy of the Demo collection, this would be `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md`. -3. Append `.atom` at the end of this address. - - For example, for the GitHub Privacy Policy of the Demo collection, this would become `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md.atom`. -4. Subscribe your RSS feed reader to the resulting address. +Subscribe to changes across the entire collection: `{collection-api-endpoint}/feed` -- - - +> For example, for all terms of the Demo collection: `http://162.19.74.224/collection-api/v1/feed` ## For all the terms of a service -Simply navigate to the history of changes for the service you are interested in and follow the same procedure as for a specific document. +Subscribe to changes for all terms of a specific service: `{collection-api-endpoint}/feed/{serviceId}` -For example, for all terms of the Demo collection, you would obtain `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub.atom`. +> For example, for all terms of GitHub in the Demo collection: `http://162.19.74.224/collection-api/v1/feed/GitHub` -- - - +## For one terms type of a service -## For all terms of a collection +Subscribe to changes for a specific terms type of a service: `{collection-api-endpoint}/feed/{serviceId}/{termsType}` -Simply append `commits.atom` to the URL of the repository. +Terms types that contain spaces or special characters must be URL-encoded. For example, "Privacy Policy" becomes `Privacy%20Policy`. -For example, for all terms of the Demo collection, you would use `https://github.com/OpenTermsArchive/demo-versions/commits.atom`. +> For example, for the GitHub Privacy Policy of the Demo collection: `http://162.19.74.224/collection-api/v1/feed/GitHub/Privacy%20Policy`