From 8b24448ff872bf7f97c68446d79b215a5c4e2020 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 25 Oct 2023 17:00:00 +0200 Subject: [PATCH 01/11] Define how to expose version through the collection metadata API --- decision-records/0004-data-api.md | 113 ++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 decision-records/0004-data-api.md diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md new file mode 100644 index 000000000..8c2222431 --- /dev/null +++ b/decision-records/0004-data-api.md @@ -0,0 +1,113 @@ +# Define how to expose version through the collection metadata API + +- Date: 2023-10-25 + +## Context and Problem Statement + +### Context + +The need to extend the current API comes as part of our collaboration with Terms of Service; Didn't Read (ToS;DR), whose web application will be adapted to obtain data from public OTA datasets instead of the ToS;DR server database. + +Currently, the terms annotated by ToS;DR are currently taken from original web documents stored on the ToS;DR server database. Open Terms Archive provides a significantly higher quality source for terms, for example by cleaning up all content that is not related to the terms, combining documents scattered across several pages, or normalising PDF documents. + +To allow the transition from historical ToS;DR's crawler and database to the publicly accessible OTA datasets, ToS;DR requires access to the content of the versions through an API. This RFC outlines the proposed solutions. + +## Proposed solutions + +### Solution A: + +#### Base URL + +`/api/:version` + +#### Endpoint + +##### `GET /version/:serviceId/:termsType/:date.md` + +Return the markdown content of the version valid for the given date + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO date string | The date for which you want the version. This date should not be in the futur | + +Note about the date: +- It is not required that this date match exactly the fetch date of a version. As versions are fetched at periodic interval the version that will be returned will corresond to the version valid for this date range. +- To have the latest version available, simple use the current date time as parameter. + +##### Returns + +- A raw markdown content when a version was found for this date +- A HTTP 404 for a date that is anterior of the first available version +- A HTTP 400 Bad Request, if the date is in the futur + +##### Example + +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z.md +``` +```markdown +Privacy Policy +============== + +Last updated: September 26, 2023 + +This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ + +ā€¦ +``` + +### Solution B: + +#### Base URL + +`/api/:version` + +#### Endpoint + +##### `GET /version/:serviceId/:termsType/:date` + +Return a JSON object containing of the version content valid for the given date along some metadata + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO date string | The date for which you want the version. This date should not be in the futur | + +Note about the date: +- It is not required that this date match exactly the fetch date of a version. As versions are fetched at periodic interval the version that will be returned will corresond to the version valid for this date range. +- To have the latest version available, simple use the current date time as parameter. + +##### Returns + +- A raw markdown content when a version was found for this date +- A HTTP 404 for a date that is anterior of the first available version +- A HTTP 400 Bad Request, if the date is in the futur + +##### Example + +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z +``` +```json +{ + "fetchDate": "2023-10-20T06:30:00.381Z", + "id": "c0dac2866fb2cdef7f8b98cc260177ac43df273b", + "content": " +Privacy Policy +============== + +Last updated: September 26, 2023 + +This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ + +ā€¦ +" +} +``` From 3a1c49a2a3974945c02575bfb39b7ae698099cea Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Mon, 20 Nov 2023 15:25:28 +0100 Subject: [PATCH 02/11] Fix typos and complete sentences --- decision-records/0004-data-api.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index 8c2222431..ebd7e3ae4 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -6,9 +6,9 @@ ### Context -The need to extend the current API comes as part of our collaboration with Terms of Service; Didn't Read (ToS;DR), whose web application will be adapted to obtain data from public OTA datasets instead of the ToS;DR server database. +The need to extend the current API comes as part of our collaboration with Terms of Service; Didn't Read (ToS;DR), whose web application will be adapted to obtain data from public Open Terms Archive collections instead of the ToS;DR server database. -Currently, the terms annotated by ToS;DR are currently taken from original web documents stored on the ToS;DR server database. Open Terms Archive provides a significantly higher quality source for terms, for example by cleaning up all content that is not related to the terms, combining documents scattered across several pages, or normalising PDF documents. +The terms annotated by ToS;DR are currently taken from original web documents stored on the ToS;DR server database. Open Terms Archive provides a significantly higher quality source for terms, for example by cleaning up all content that is not related to the terms, combining documents scattered across several pages, or normalising PDF documents into Markdown. To allow the transition from historical ToS;DR's crawler and database to the publicly accessible OTA datasets, ToS;DR requires access to the content of the versions through an API. This RFC outlines the proposed solutions. @@ -24,7 +24,7 @@ To allow the transition from historical ToS;DR's crawler and database to the pub ##### `GET /version/:serviceId/:termsType/:date.md` -Return the markdown content of the version valid for the given date +Return the Markdown content of the version of the terms that was applicable at the given date ##### Parameters @@ -35,8 +35,8 @@ Return the markdown content of the version valid for the given date | date | URL-encoded ISO date string | The date for which you want the version. This date should not be in the futur | Note about the date: -- It is not required that this date match exactly the fetch date of a version. As versions are fetched at periodic interval the version that will be returned will corresond to the version valid for this date range. -- To have the latest version available, simple use the current date time as parameter. +- It is not required that this date matches exactly the fetch date of a version. As versions are fetched at a periodic interval, the version that will be returned will be the one that was applicable at the provided date. +- To get the latest version available, simply use the current date as parameter. ##### Returns @@ -70,7 +70,7 @@ This privacy policy explains how, why and under what conditions the Open Terms A ##### `GET /version/:serviceId/:termsType/:date` -Return a JSON object containing of the version content valid for the given date along some metadata +Returns a JSON object containing the version content valid for the given date along with metadata. ##### Parameters @@ -78,11 +78,11 @@ Return a JSON object containing of the version content valid for the given date | --------- | ------ | ---------------------- | | serviceId | URL-encoded string | The ID of the service | | termsType | URL-encoded string | The name of terms type | -| date | URL-encoded ISO date string | The date for which you want the version. This date should not be in the futur | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | Note about the date: -- It is not required that this date match exactly the fetch date of a version. As versions are fetched at periodic interval the version that will be returned will corresond to the version valid for this date range. -- To have the latest version available, simple use the current date time as parameter. +- It is not required that this date matches exactly the fetch date of a version. As versions are fetched at a periodic interval, the version that will be returned will be the one that was applicable at the provided date. +- To get the latest version available, simply use the current date as parameter. ##### Returns From b0a516b6ff1340b822c5479c80098203e034a97f Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Mon, 20 Nov 2023 15:39:11 +0100 Subject: [PATCH 03/11] Add solution C to RFC 0004 --- decision-records/0004-data-api.md | 58 +++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index ebd7e3ae4..d66f33563 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -111,3 +111,61 @@ This privacy policy explains how, why and under what conditions the Open Terms A " } ``` + +### Solution C + +This solution aims at allowing caching and providing metadata through standard HTTP methods. By redirecting to the canonical version name instead of replying with the applicable content, we enable proxies, the server and the user agent to leverage ETags cache the actual content, which might be several hundreds of kB. It also enables the client to know the time of record of the version. + +#### Base URL + +`/api/:version` + +#### Endpoint + +##### `GET /version/:serviceId/:termsType/:date.md` + +Identifies the Markdown content of the version of the terms that was applicable at the given date and provides its contents. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | + +Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. +- To get the latest version available, simply use the current date as parameter. + +##### Returns + +- HTTP 200 with the Markdown content as body when a version is found for this exact date +- HTTP 302 with the content when a version is applicable at this date, with the `Location` field of the response giving the exact date +- HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `{"error": "Requested version is in the future"}` if the date is in the future. + +##### Example + +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z.md +``` +```text +HTTP 302 +Location: /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +``` +```GET +/version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +``` +```markdown +HTTP 200 +- - - +Privacy Policy +============== + +Last updated: September 26, 2023 + +This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ + +ā€¦ +``` From a9bd33b2398b85d7503762643244980c5592be78 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Mon, 20 Nov 2023 17:51:25 +0100 Subject: [PATCH 04/11] Improve API definition Co-authored-by: Matti Schneider --- decision-records/0004-data-api.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index d66f33563..c4a12a108 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -10,7 +10,7 @@ The need to extend the current API comes as part of our collaboration with Terms The terms annotated by ToS;DR are currently taken from original web documents stored on the ToS;DR server database. Open Terms Archive provides a significantly higher quality source for terms, for example by cleaning up all content that is not related to the terms, combining documents scattered across several pages, or normalising PDF documents into Markdown. -To allow the transition from historical ToS;DR's crawler and database to the publicly accessible OTA datasets, ToS;DR requires access to the content of the versions through an API. This RFC outlines the proposed solutions. +To allow the transition from historical ToS;DR's crawler and database to the publicly accessible Open Terms Archive collections, ToS;DR requires access to the content of the versions. Datasets are not satisfactory as they are produced on a weekly basis, whereas a workflow supporting annotation of just-added terms is required by ToS;DR. This RFC outlines possible implementations of an API providing this data. ## Proposed solutions @@ -32,17 +32,18 @@ Return the Markdown content of the version of the terms that was applicable at t | --------- | ------ | ---------------------- | | serviceId | URL-encoded string | The ID of the service | | termsType | URL-encoded string | The name of terms type | -| date | URL-encoded ISO date string | The date for which you want the version. This date should not be in the futur | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. - It is not required that this date matches exactly the fetch date of a version. As versions are fetched at a periodic interval, the version that will be returned will be the one that was applicable at the provided date. - To get the latest version available, simply use the current date as parameter. ##### Returns -- A raw markdown content when a version was found for this date -- A HTTP 404 for a date that is anterior of the first available version -- A HTTP 400 Bad Request, if the date is in the futur +- HTTP 200 with the Markdown content as body when a version is found for this date +- HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `{"error": "Requested version is in the future"}` if the date is in the future. ##### Example @@ -50,6 +51,8 @@ Note about the date: GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z.md ``` ```markdown +HTTP 200 +- - - Privacy Policy ============== @@ -81,14 +84,15 @@ Returns a JSON object containing the version content valid for the given date al | date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. - It is not required that this date matches exactly the fetch date of a version. As versions are fetched at a periodic interval, the version that will be returned will be the one that was applicable at the provided date. - To get the latest version available, simply use the current date as parameter. ##### Returns -- A raw markdown content when a version was found for this date -- A HTTP 404 for a date that is anterior of the first available version -- A HTTP 400 Bad Request, if the date is in the futur +- HTTP 200 with a JSON object containing the Markdown content as body when a version is found for this date +- HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `{"error": "Requested version is in the future"}` if the date is in the future. ##### Example From bc4a6639e48da5081b85eaafe0529f5c1735c8f8 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 5 Dec 2023 09:33:05 +0100 Subject: [PATCH 05/11] Fix example --- decision-records/0004-data-api.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index c4a12a108..81525e19f 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -102,17 +102,9 @@ GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381 ```json { "fetchDate": "2023-10-20T06:30:00.381Z", + "snapshotsIds": ["c0dac2866fb2cdef7f8b98cc260177ac43df273b"], "id": "c0dac2866fb2cdef7f8b98cc260177ac43df273b", - "content": " -Privacy Policy -============== - -Last updated: September 26, 2023 - -This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ - -ā€¦ -" + "content": "\nPrivacy Policy\n==============\nLast updated: September 26, 2023\nThis privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰\nā€¦\n" } ``` From 5c84a4545f77528248342586351bf8fc4aafec3e Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 5 Dec 2023 11:42:31 +0100 Subject: [PATCH 06/11] Improve wording Co-authored-by: Matti Schneider --- decision-records/0004-data-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index 81525e19f..f6d057a9f 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -1,4 +1,4 @@ -# Define how to expose version through the collection metadata API +# Expose versions data through the collection API - Date: 2023-10-25 From 460a8c1d2df51922bbba052a2eb366816fd828e3 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 5 Dec 2023 11:58:55 +0100 Subject: [PATCH 07/11] Improve titles --- decision-records/0004-data-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index f6d057a9f..529901abd 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -14,7 +14,7 @@ To allow the transition from historical ToS;DR's crawler and database to the pub ## Proposed solutions -### Solution A: +### Solution A #### Base URL @@ -63,7 +63,7 @@ This privacy policy explains how, why and under what conditions the Open Terms A ā€¦ ``` -### Solution B: +### Solution B #### Base URL From 9cd4eebcea636815d6fe14e6cea0cca6b143dca7 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 5 Dec 2023 11:59:00 +0100 Subject: [PATCH 08/11] Add solution D --- decision-records/0004-data-api.md | 137 ++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index 529901abd..eb883ea20 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -165,3 +165,140 @@ This privacy policy explains how, why and under what conditions the Open Terms A ā€¦ ``` + +### Solution D + +Solution D is a combination of all A, B and C aiming at keeping the best parts of each: + +- A for ease of content access +- B for metadata extensibility +- C for performance capabilities + +It has the added benefit of being possibly split in implementation in two parts, which are made clear in the proposal. + +#### Base URL + +`/api/:version` + +#### Endpoint with JSON content-type + +##### `GET /version/:serviceId/:termsType/:date` + +Return the contents of the version of the terms that was applicable at the given date, with metadata, in JSON format. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | + +Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. +- To get the latest version available, simply use the current date as parameter. + +##### Returns + +- HTTP 200 with a JSON object as body when a version is found for this exact date, containing metadata and a `content` property with the Markdown content, JSON-escaped +- HTTP 302 with the content when a version is applicable at this date, with the `Location` field of the response giving the exact date +- HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `{"error": "Requested date is in the future, no version can exist there"}` if the date is in the future. + +##### Example + +
+ +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z +``` +``` +HTTP 302 +Location: /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z +``` +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z +``` +```json +HTTP 200 +ETag: c0dac2866fb2cdef7f8b98cc260177ac43df273b +- - - +{ + "fetchDate": "2023-09-20T12:30:00.381Z", + "snapshotsIds": ["c0dac2866fb2cdef7f8b98cc260177ac43df273b"], + "id": "c0dac2866fb2cdef7f8b98cc260177ac43df273b", + "content": "\nPrivacy Policy\n==============\nLast updated: September 26, 2023\nThis privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰\nā€¦\n" +} +``` +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z +If-none-match: c0dac2866fb2cdef7f8b98cc260177ac43df273b +``` +```json +HTTP 304 +``` + +
+ +#### Endpoint with Markdown content-type + +##### `GET /version/:serviceId/:termsType/:date.md` + +Return the contents of the version of the terms that was applicable at the given date in Markdown format. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | + +Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. +- To get the latest version available, simply use the current date as parameter. + +##### Returns + +- HTTP 200 with the Markdown content as body when a version is found for this exact date +- HTTP 302 with the content when a version is applicable at this date, with the `Location` field of the response giving the exact date +- HTTP 404 Not Found with Markdown content `# Error\n\n_No version found for date _` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `# Error\n\n_Requested date is in the future, no version can exist there_` if the date is in the future. + +##### Examples + +
+ +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-10-24T14%3A41%3A42.381Z.md +``` +``` +HTTP 302 +Location: /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +``` +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +``` +```markdown +HTTP 200 +ETag: c0dac2866fb2cdef7f8b98cc260177ac43df273b +- - - +Privacy Policy +============== + +Last updated: September 26, 2023 + +This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ + +ā€¦ +``` +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +If-none-match: c0dac2866fb2cdef7f8b98cc260177ac43df273b +``` + +```markdown +HTTP 304 +``` + +
From b535f57c0dd98ef9f47a0eb2213a4c1054fa0c76 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 5 Dec 2023 16:29:11 +0100 Subject: [PATCH 09/11] Add solution E --- decision-records/0004-data-api.md | 98 +++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index eb883ea20..915e803c5 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -302,3 +302,101 @@ HTTP 304 ``` + +### Solution E + +Solution E is a combination of solutions A and B without the premature performance optimization of solution C. + +#### Base URL + +`/api/:version` + +#### Endpoint with JSON content-type + +##### `GET /version/:serviceId/:termsType/:date` + +Return the contents of the version of the terms that was applicable at the given date, with metadata, in JSON format. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | + +Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. +- To get the latest version available, simply use the current date as parameter. + +##### Returns + +- HTTP 200 with a JSON object as body when a version is applicable at this date, containing metadata and a `content` property with the Markdown content, JSON-escaped +- HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `{"error": "Requested date is in the future, no version can exist there"}` if the date is in the future. + +##### Example + +
+ +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z +``` +```json +HTTP 200 +- - - +{ + "fetchDate": "2023-09-20T12:30:00.381Z", + "snapshotsIds": ["c0dac2866fb2cdef7f8b98cc260177ac43df273b"], + "id": "c0dac2866fb2cdef7f8b98cc260177ac43df273b", + "content": "\nPrivacy Policy\n==============\nLast updated: September 26, 2023\nThis privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰\nā€¦\n" +} +``` + +
+ +#### Endpoint with Markdown content-type + +##### `GET /version/:serviceId/:termsType/:date.md` + +Return the contents of the version of the terms that was applicable at the given date in Markdown format. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------- | +| serviceId | URL-encoded string | The ID of the service | +| termsType | URL-encoded string | The name of terms type | +| date | URL-encoded ISO 8601 datetime string | The date and time for which the version is requested | + +Note about the date: +- A full date and time is required, and not a simple date (such as `2023-10-24`), to avoid ambiguities on days where a version changed, and timezone differences between client and server. +- To get the latest version available, simply use the current date as parameter. + +##### Returns + +- HTTP 200 with the Markdown content as body when a version is applicable at this date +- HTTP 404 Not Found with Markdown content `# Error\n\n_No version found for date _` for a date that is anterior to the first available version +- HTTP 400 Bad Request with JSON content `# Error\n\n_Requested date is in the future, no version can exist there_` if the date is in the future. + +##### Examples + +
+ +``` +GET /version/Open%20Terms%20Archive/Privacy%20Policy/2023-09-26T12%3A43%3A39.238Z.md +``` +```markdown +HTTP 200 +- - - +Privacy Policy +============== + +Last updated: September 26, 2023 + +This privacy policy explains how, why and under what conditions the Open Terms Archive (OTA) site collects personal information and how it is used. Our privacy policy will change over time. And of course, we also record the changes of [our own documents](https://github.com/OpenTermsArchive/demo-versions/tree/main/Open%20Terms%20Archive) šŸ˜‰ + +ā€¦ +``` + +
From 18dcc7dc36f2c5f9407ee2b2a0808ca366aff099 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 6 Dec 2023 09:37:59 +0100 Subject: [PATCH 10/11] Add decision outcome --- decision-records/0004-data-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index 915e803c5..f61a5068d 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -400,3 +400,7 @@ This privacy policy explains how, why and under what conditions the Open Terms A ``` + +## Decision Outcome + +[After consulting the community](https://github.com/OpenTermsArchive/engine/pull/1028), the solution E is retained. It integrates the content accessibility of Solution A and the metadata extensibility of Solution B. It also avoids introducing early performance optimisations at this stage. From 281e17e472e57a7aafdf9c19c5260247d71938a7 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Mon, 11 Dec 2023 11:33:08 +0100 Subject: [PATCH 11/11] Improve Solution E Co-authored-by: Matti Schneider --- decision-records/0004-data-api.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/decision-records/0004-data-api.md b/decision-records/0004-data-api.md index f61a5068d..0d92dd66a 100644 --- a/decision-records/0004-data-api.md +++ b/decision-records/0004-data-api.md @@ -305,7 +305,7 @@ HTTP 304 ### Solution E -Solution E is a combination of solutions A and B without the premature performance optimization of solution C. +Solution E is the same as solution D without the premature performance optimization introduced in solution C. #### Base URL @@ -333,7 +333,8 @@ Note about the date: - HTTP 200 with a JSON object as body when a version is applicable at this date, containing metadata and a `content` property with the Markdown content, JSON-escaped - HTTP 404 Not Found with JSON content `{"error": "No version found for date "}` for a date that is anterior to the first available version -- HTTP 400 Bad Request with JSON content `{"error": "Requested date is in the future, no version can exist there"}` if the date is in the future. +- HTTP 400 Bad Request with JSON content `{ "error": " is not a valid ISO 8601 date and time" }` if the date is not a valid ISO 8601 date time. +- HTTP 416 Range Not Satisfiable with JSON content `{ "error": "Requested date is in the future, no version can exist there" }` if the date is in the future. ##### Example @@ -377,7 +378,8 @@ Note about the date: - HTTP 200 with the Markdown content as body when a version is applicable at this date - HTTP 404 Not Found with Markdown content `# Error\n\n_No version found for date _` for a date that is anterior to the first available version -- HTTP 400 Bad Request with JSON content `# Error\n\n_Requested date is in the future, no version can exist there_` if the date is in the future. +- HTTP 400 Bad Request with Markdown content `# Error\n\n_Requested date is not a valid ISO 8601 date time_` if the date is not a valid ISO 8601 date time. +- HTTP 416 Range Not Satisfiable with Markdown content `# Error\n\n_Requested date is in the future, no version can exist there_` if the date is in the future. ##### Examples