From 47f042f72bdc023c71af7110b408770924c0f30c Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Sat, 31 Mar 2018 22:37:28 -0500 Subject: Add proposals/0000-http-pinning-service-api.md --- proposals/0000-http-pinning-service-api.md | 205 +++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 proposals/0000-http-pinning-service-api.md diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md new file mode 100644 index 0000000..9fdc5ac --- /dev/null +++ b/proposals/0000-http-pinning-service-api.md @@ -0,0 +1,205 @@ + +Title: **DEP-0000: HTTP Pinning Service API** + +Short Name: `0000-http-pinning-service-api` + +Type: Standard + +Status: Draft (as of 2018-03-31) + +Github PR: (add HTTPS link here after PR is opened) + +Authors: Paul Frazee + + +# Summary [summary]: #summary + +An HTTP API for adding and removing Dat data. + + +# Motivation [motivation]: #motivation + +Users frequently make use of "pinning services" to keep their Dat data online +independently of their personal devices. By specifying a standard API for +accessing pinning services, we can integrate interfaces for these services to +Dat clients (including the Dat CLI and Beaker Browser). For example, in the Dat +CLI, it will be possible to execute commands such as: + +``` +dat publish --name myarchive my-pinning-service.com +``` + + +# Service description (PSA) document [service-description]: #service-description + +Servers should host the PSA service-description document at `/.well-known/psa`. +It may be fetched using a GET request. This document will fit the following schema: + +```json +{ + "PSA": 1, + "title": "My Pinning Service", + "description": "Keep your Dats online!", + "links": [{ + "rel": "user-accounts-api.com/v1", + "title": "User accounts API", + "href": "/v1/accounts" + }, { + "rel": "datprotocol.com/deps/0000-http-pinning-service-api", + "title": "Dat pinning API", + "href": "/v1/dats" + }] +} +``` + +You can read more about the [PSA Service Discovery +Protocol](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol). + +The PSA document must provide links to two API resources: the User Accounts +API, and the Dat Pinning API. These resources should be indicated by the +`user-accounts-api.com/v1` and `datprotocol.com/deps/0000-http-pinning-service-api` +rel-types, respectively. (These rel-types will need to be updated +with the final URLs for their specifications.) If either API is absent from +the PSA document, the service will be rejected. + + +# User accounts API [user-accounts-api]: #user-accounts-api + +The user-accounts API should provide the following resources: + +``` +POST /register Register a new account. +POST /verify Verify the email address of a recently-registered account. +POST /login Create a new session with an existing account. +POST /logout End a session. +GET /account Get information about the account attached to the current session. +POST /account Update information about the account attached to the current session. +``` + +TODO- specify each route in detail. + +Full documentation for this API should be made available at https://user-accounts-api.com. + +## User registration flow [user-registration-flow]: #user-registration-flow + +### Step 1. Register + +User POSTS to `/register` with body: + +```json +{ + email: String + username: String + password: String +} +``` + +Server creates a new account for the user. A random 32-byte email-verification +nonce is created. The user record indicates: + +scopes|isEmailVerified|emailVerifyNonce +------|---------------|---------------- +none|false|XXX + +Server sends an email to the user with the `emailVerifyNonce`. + +Server responds 200 or 204. + +### Step 2. Verify (POST /verify) + +User POSTS `/v1/verify` with JSON body: + +``` +{ + username: String, username of the account + nonce: String, verification nonce +} +``` + +Server updates user record to indicate: + +scopes|isEmailVerified|emailVerifyNonce +------|---------------|---------------- +user|true|null + +Sever generates a session and session token, and responds 200 with a JSON body: + +```json +{ + sessionToken: String, users session token +} +``` + +## Session login flow [session-login-flow]: #session-login-flow + +User POSTS to `/login` with body: + +```json +{ + username: String + password: String +} +``` + +Sever generates a session and session token, and responds 200 with a JSON body: + +```json +{ + sessionToken: String, users session token +} +``` + + +# Dat pinning API [dat-pinning-api]: #dat-pinning-api + +The dat pinning API should provide the following resources: + +``` +GET / List all Dat data pinned by this account. +POST /add Add a Dat to this account's list of pins. +POST /remove Remove a Dat from this account's list of pins. +GET /item/:key Get information about a Dat in the account's list of pins. + Key may be the pubkey or name of the dat. +POST /item/:key Update information about a Dat in the account's list of pins. + Key may be the pubkey or name of the dat. +``` + +TODO- specify each route in detail. + + +# Authentication [authentication]: #authentication + +Clients should use the [User accounts API](#user-accounts-api) to fetch a +session token from the service. This token should be included in the +`Authentication` header using the `Bearer` scheme. + + +# Error responses [error-responses]: #error-responses + +All error responses should respond with a JSON body which matches the +following schema: + +```json +{ + message: String +} +``` + +The content of `message` will be displayed to the user. It should explain the +error and, if appropriate, give steps for solving the issue. Other fields may +be included in the response. + + +# Rationale and alternatives [alternatives]: #alternatives + +- The motivations and drawbacks of the PSA Service Document are discussed +[here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). +Without a description format, it becomes difficult to handle user +authentication. We would probably need to use the HTTP Basic scheme and remove +any mechanisms for registering new accounts. + + +# Changelog [changelog]: #changelog + +- YYYY-MM-DD: First complete draft submitted for review + -- cgit v1.2.3 From 99e621f9285ad8b49462e20c3562d20fdf0b79bd Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Sat, 31 Mar 2018 22:41:26 -0500 Subject: Formatting fixes --- proposals/0000-http-pinning-service-api.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 9fdc5ac..178b149 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -12,12 +12,14 @@ Github PR: (add HTTPS link here after PR is opened) Authors: Paul Frazee -# Summary [summary]: #summary +# Summary [summary]: +#summary An HTTP API for adding and removing Dat data. -# Motivation [motivation]: #motivation +# Motivation +[motivation]: #motivation Users frequently make use of "pinning services" to keep their Dat data online independently of their personal devices. By specifying a standard API for @@ -30,7 +32,8 @@ dat publish --name myarchive my-pinning-service.com ``` -# Service description (PSA) document [service-description]: #service-description +# Service description (PSA) document +[service-description]: #service-description Servers should host the PSA service-description document at `/.well-known/psa`. It may be fetched using a GET request. This document will fit the following schema: @@ -63,7 +66,8 @@ with the final URLs for their specifications.) If either API is absent from the PSA document, the service will be rejected. -# User accounts API [user-accounts-api]: #user-accounts-api +# User accounts API +[user-accounts-api]: #user-accounts-api The user-accounts API should provide the following resources: @@ -86,7 +90,7 @@ Full documentation for this API should be made available at https://user-account User POSTS to `/register` with body: -```json +``` { email: String username: String @@ -150,7 +154,8 @@ Sever generates a session and session token, and responds 200 with a JSON body: ``` -# Dat pinning API [dat-pinning-api]: #dat-pinning-api +# Dat pinning API +[dat-pinning-api]: #dat-pinning-api The dat pinning API should provide the following resources: @@ -167,14 +172,16 @@ POST /item/:key Update information about a Dat in the account's list of pins. TODO- specify each route in detail. -# Authentication [authentication]: #authentication +# Authentication +[authentication]: #authentication Clients should use the [User accounts API](#user-accounts-api) to fetch a session token from the service. This token should be included in the `Authentication` header using the `Bearer` scheme. -# Error responses [error-responses]: #error-responses +# Error responses +[error-responses]: #error-responses All error responses should respond with a JSON body which matches the following schema: @@ -190,7 +197,8 @@ error and, if appropriate, give steps for solving the issue. Other fields may be included in the response. -# Rationale and alternatives [alternatives]: #alternatives +# Rationale and alternatives +[alternatives]: #alternatives - The motivations and drawbacks of the PSA Service Document are discussed [here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). @@ -199,7 +207,8 @@ authentication. We would probably need to use the HTTP Basic scheme and remove any mechanisms for registering new accounts. -# Changelog [changelog]: #changelog +# Changelog +[changelog]: #changelog - YYYY-MM-DD: First complete draft submitted for review -- cgit v1.2.3 From 11b1c8509f572e1794f7c36cc49cbbd3042ed13b Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Sat, 31 Mar 2018 22:42:07 -0500 Subject: Formatting fixes --- proposals/0000-http-pinning-service-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 178b149..4536494 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -12,8 +12,8 @@ Github PR: (add HTTPS link here after PR is opened) Authors: Paul Frazee -# Summary [summary]: -#summary +# Summary +[summary]: #summary An HTTP API for adding and removing Dat data. @@ -128,7 +128,7 @@ user|true|null Sever generates a session and session token, and responds 200 with a JSON body: -```json +``` { sessionToken: String, users session token } @@ -138,7 +138,7 @@ Sever generates a session and session token, and responds 200 with a JSON body: User POSTS to `/login` with body: -```json +``` { username: String password: String @@ -147,7 +147,7 @@ User POSTS to `/login` with body: Sever generates a session and session token, and responds 200 with a JSON body: -```json +``` { sessionToken: String, users session token } @@ -186,7 +186,7 @@ session token from the service. This token should be included in the All error responses should respond with a JSON body which matches the following schema: -```json +``` { message: String } -- cgit v1.2.3 From 218d4df3f494219aa97cabad2440bdbdf748649f Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Sat, 31 Mar 2018 22:43:30 -0500 Subject: More.....formatting fixes --- proposals/0000-http-pinning-service-api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 4536494..eb51c09 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -84,7 +84,8 @@ TODO- specify each route in detail. Full documentation for this API should be made available at https://user-accounts-api.com. -## User registration flow [user-registration-flow]: #user-registration-flow +## User registration flow +[user-registration-flow]: #user-registration-flow ### Step 1. Register @@ -134,7 +135,8 @@ Sever generates a session and session token, and responds 200 with a JSON body: } ``` -## Session login flow [session-login-flow]: #session-login-flow +## Session login flow +[session-login-flow]: #session-login-flow User POSTS to `/login` with body: -- cgit v1.2.3 From 338dc84727054b2112a909c0d31c1b6b0269bc94 Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Sat, 31 Mar 2018 22:44:01 -0500 Subject: Add PR link --- proposals/0000-http-pinning-service-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index eb51c09..ec7a9f0 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -7,7 +7,7 @@ Type: Standard Status: Draft (as of 2018-03-31) -Github PR: (add HTTPS link here after PR is opened) +Github PR: https://github.com/datprotocol/DEPs/pull/19 Authors: Paul Frazee -- cgit v1.2.3 From 113d87dd7b3aacbf60aa0150cd9c371013e50d14 Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Tue, 3 Apr 2018 20:42:39 -0500 Subject: Finish first draft of 0000-http-pinning-service-api.md --- proposals/0000-http-pinning-service-api.md | 150 ++++++++++++++++++++--------- 1 file changed, 105 insertions(+), 45 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index ec7a9f0..5aeb4cd 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -72,106 +72,160 @@ the PSA document, the service will be rejected. The user-accounts API should provide the following resources: ``` -POST /register Register a new account. -POST /verify Verify the email address of a recently-registered account. POST /login Create a new session with an existing account. POST /logout End a session. GET /account Get information about the account attached to the current session. -POST /account Update information about the account attached to the current session. ``` -TODO- specify each route in detail. - Full documentation for this API should be made available at https://user-accounts-api.com. -## User registration flow -[user-registration-flow]: #user-registration-flow +## POST /login +[user-accounts-api-post-login]: #user-accounts-api-post-login -### Step 1. Register +Create a new session with an existing account. -User POSTS to `/register` with body: +Request body (JSON). All fields required: ``` { - email: String username: String password: String } ``` -Server creates a new account for the user. A random 32-byte email-verification -nonce is created. The user record indicates: +Handler should generate a session and return the identifier in the response. +Response body (JSON): + +``` +{ + sessionToken: String +} +``` + +## POST /logout +[user-accounts-api-post-logout]: #user-accounts-api-post-logout -scopes|isEmailVerified|emailVerifyNonce -------|---------------|---------------- -none|false|XXX +End a session. -Server sends an email to the user with the `emailVerifyNonce`. +Request should include [authentication header](#authentication). -Server responds 200 or 204. +## GET /account +[user-accounts-api-get-account]: #user-accounts-api-get-account -### Step 2. Verify (POST /verify) +Get information about the account attached to the current session. -User POSTS `/v1/verify` with JSON body: +Request should include [authentication header](#authentication). + +Response body (JSON): ``` { - username: String, username of the account - nonce: String, verification nonce + email: String, the accounts email (required) + username: String, the accounts username (required) + diskUsage: Number, how much disk space has the user's data taken? (optional) + diskQuota: Number, how much disk space can the user's data take? (optional) + updatedAt: Number, the Unix timestamp of the last time the user account was updated (optional) + createdAt: Number, the Unix timestamp of the last time the user account was updated (optional) } ``` -Server updates user record to indicate: -scopes|isEmailVerified|emailVerifyNonce -------|---------------|---------------- -user|true|null +# Dat pinning API +[dat-pinning-api]: #dat-pinning-api -Sever generates a session and session token, and responds 200 with a JSON body: +The dat pinning API should provide the following resources: + +``` +GET / List all Dat data pinned by this account. +POST /add Add a Dat to this account's list of pins. +POST /remove Remove a Dat from this account's list of pins. +GET /item/:key Get information about a Dat in the account's list of pins. +POST /item/:key Update information about a Dat in the account's list of pins. +``` + +## GET / +[dat-pinning-api-get-root]: #dat-pinning-api-get-root + +List all Dat data pinned by this account. + +Request should include [authentication header](#authentication). + +Response body (JSON): ``` { - sessionToken: String, users session token + items: [{ + url: String, dat url + name: String, optional shortname assigned by the user + title: String, optional title extracted from the dat's manifest file + description: String, optional description extracted from the dat's manifest file + urls: Array of Strings, optional list of URLs the dat can be accessed at + }] } ``` -## Session login flow -[session-login-flow]: #session-login-flow +## POST /add +[dat-pinning-api-post-add]: #dat-pinning-api-post-add + +Add a Dat to this account's list of pins. -User POSTS to `/login` with body: +Request should include [authentication header](#authentication). +Request body (JSON): ``` { - username: String - password: String + url: String, required url/key of the dat + name: String, optional shortname for the archive + domains: Array of Strings, optional list of domain-names the dat should be made available at } ``` -Sever generates a session and session token, and responds 200 with a JSON body: +## POST /remove +[dat-pinning-api-post-remove]: #dat-pinning-api-post-remove + +Remove a Dat from this account's list of pins. + +Request should include [authentication header](#authentication). +Request body (JSON): ``` { - sessionToken: String, users session token + url: String, required url/key of the dat } ``` +## GET /item/:key +[dat-pinning-api-get-item]: #dat-pinning-api-get-item -# Dat pinning API -[dat-pinning-api]: #dat-pinning-api +Get information about a Dat in the account's list of pins. Key must be the +pubkey of the dat. -The dat pinning API should provide the following resources: +Response body (JSON): ``` -GET / List all Dat data pinned by this account. -POST /add Add a Dat to this account's list of pins. -POST /remove Remove a Dat from this account's list of pins. -GET /item/:key Get information about a Dat in the account's list of pins. - Key may be the pubkey or name of the dat. -POST /item/:key Update information about a Dat in the account's list of pins. - Key may be the pubkey or name of the dat. +{ + url: String, dat url + name: String, optional shortname assigned by the user + title: String, optional title extracted from the dat's manifest file + description: String, optional description extracted from the dat's manifest file + urls: Array of Strings, optional list of URLs the dat can be accessed at +} ``` -TODO- specify each route in detail. +## POST /item/:key +[dat-pinning-api-post-item]: #dat-pinning-api-post-item + +Update information about a Dat in the account's list of pins. Key must be the +pubkey of the dat. + +Request body (JSON): + +``` +{ + name: String, optional shortname for the archive + domains: Array of Strings, optional list of domain-names the dat should be made available at +} +``` # Authentication @@ -209,6 +263,12 @@ authentication. We would probably need to use the HTTP Basic scheme and remove any mechanisms for registering new accounts. +# Unresolved questions +[unresolved]: #unresolved-questions + +- Does the registration flow need to be included in the spec? + + # Changelog [changelog]: #changelog -- cgit v1.2.3 From 5a3df8c3b4beede5bab94d2fb332bc5abbdcad30 Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Wed, 4 Apr 2018 13:19:09 -0500 Subject: Explain if diskQuota == 0 --- proposals/0000-http-pinning-service-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 5aeb4cd..75dff6c 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -129,6 +129,8 @@ Response body (JSON): } ``` +If `diskQuota` is not included or is set to 0, the service is acting as a "registry" and will not host the files. + # Dat pinning API [dat-pinning-api]: #dat-pinning-api -- cgit v1.2.3 From f41a7b063363c0e3c6f76cc5c992ca134fc7e2f7 Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Wed, 4 Apr 2018 13:19:34 -0500 Subject: Update reltypes to use PURLs --- proposals/0000-http-pinning-service-api.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 75dff6c..87b026c 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -44,11 +44,11 @@ It may be fetched using a GET request. This document will fit the following sche "title": "My Pinning Service", "description": "Keep your Dats online!", "links": [{ - "rel": "user-accounts-api.com/v1", + "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-account-api", "title": "User accounts API", "href": "/v1/accounts" }, { - "rel": "datprotocol.com/deps/0000-http-pinning-service-api", + "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-dats-api", "title": "Dat pinning API", "href": "/v1/dats" }] @@ -77,8 +77,6 @@ POST /logout End a session. GET /account Get information about the account attached to the current session. ``` -Full documentation for this API should be made available at https://user-accounts-api.com. - ## POST /login [user-accounts-api-post-login]: #user-accounts-api-post-login -- cgit v1.2.3 From ddecc70f08e203f977b04002610b21fb68cf67bb Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Wed, 4 Apr 2018 13:20:19 -0500 Subject: Rename urls field to additionalUrls --- proposals/0000-http-pinning-service-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 87b026c..7dcaf1f 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -159,7 +159,7 @@ Response body (JSON): name: String, optional shortname assigned by the user title: String, optional title extracted from the dat's manifest file description: String, optional description extracted from the dat's manifest file - urls: Array of Strings, optional list of URLs the dat can be accessed at + additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at }] } ``` @@ -208,7 +208,7 @@ Response body (JSON): name: String, optional shortname assigned by the user title: String, optional title extracted from the dat's manifest file description: String, optional description extracted from the dat's manifest file - urls: Array of Strings, optional list of URLs the dat can be accessed at + additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at } ``` -- cgit v1.2.3 From 1b5abca10b8dc583a398a4f228a4a75d61c2ae0d Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Mon, 9 Apr 2018 20:32:39 -0500 Subject: User email field is optional --- proposals/0000-http-pinning-service-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md index 7dcaf1f..ae91c3e 100644 --- a/proposals/0000-http-pinning-service-api.md +++ b/proposals/0000-http-pinning-service-api.md @@ -118,8 +118,8 @@ Response body (JSON): ``` { - email: String, the accounts email (required) username: String, the accounts username (required) + email: String, the accounts email (optional) diskUsage: Number, how much disk space has the user's data taken? (optional) diskQuota: Number, how much disk space can the user's data take? (optional) updatedAt: Number, the Unix timestamp of the last time the user account was updated (optional) -- cgit v1.2.3 From 2e652929c644a3268e1dbc5fd5ad30c90e704f65 Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Wed, 18 Apr 2018 12:40:42 -0500 Subject: Assign DEP-0003: HTTP Pinning Service API --- proposals/0000-http-pinning-service-api.md | 276 ---------------------------- proposals/0003-http-pinning-service-api.md | 277 +++++++++++++++++++++++++++++ 2 files changed, 277 insertions(+), 276 deletions(-) delete mode 100644 proposals/0000-http-pinning-service-api.md create mode 100644 proposals/0003-http-pinning-service-api.md diff --git a/proposals/0000-http-pinning-service-api.md b/proposals/0000-http-pinning-service-api.md deleted file mode 100644 index ae91c3e..0000000 --- a/proposals/0000-http-pinning-service-api.md +++ /dev/null @@ -1,276 +0,0 @@ - -Title: **DEP-0000: HTTP Pinning Service API** - -Short Name: `0000-http-pinning-service-api` - -Type: Standard - -Status: Draft (as of 2018-03-31) - -Github PR: https://github.com/datprotocol/DEPs/pull/19 - -Authors: Paul Frazee - - -# Summary -[summary]: #summary - -An HTTP API for adding and removing Dat data. - - -# Motivation -[motivation]: #motivation - -Users frequently make use of "pinning services" to keep their Dat data online -independently of their personal devices. By specifying a standard API for -accessing pinning services, we can integrate interfaces for these services to -Dat clients (including the Dat CLI and Beaker Browser). For example, in the Dat -CLI, it will be possible to execute commands such as: - -``` -dat publish --name myarchive my-pinning-service.com -``` - - -# Service description (PSA) document -[service-description]: #service-description - -Servers should host the PSA service-description document at `/.well-known/psa`. -It may be fetched using a GET request. This document will fit the following schema: - -```json -{ - "PSA": 1, - "title": "My Pinning Service", - "description": "Keep your Dats online!", - "links": [{ - "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-account-api", - "title": "User accounts API", - "href": "/v1/accounts" - }, { - "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-dats-api", - "title": "Dat pinning API", - "href": "/v1/dats" - }] -} -``` - -You can read more about the [PSA Service Discovery -Protocol](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol). - -The PSA document must provide links to two API resources: the User Accounts -API, and the Dat Pinning API. These resources should be indicated by the -`user-accounts-api.com/v1` and `datprotocol.com/deps/0000-http-pinning-service-api` -rel-types, respectively. (These rel-types will need to be updated -with the final URLs for their specifications.) If either API is absent from -the PSA document, the service will be rejected. - - -# User accounts API -[user-accounts-api]: #user-accounts-api - -The user-accounts API should provide the following resources: - -``` -POST /login Create a new session with an existing account. -POST /logout End a session. -GET /account Get information about the account attached to the current session. -``` - -## POST /login -[user-accounts-api-post-login]: #user-accounts-api-post-login - -Create a new session with an existing account. - -Request body (JSON). All fields required: - -``` -{ - username: String - password: String -} -``` - -Handler should generate a session and return the identifier in the response. -Response body (JSON): - -``` -{ - sessionToken: String -} -``` - -## POST /logout -[user-accounts-api-post-logout]: #user-accounts-api-post-logout - -End a session. - -Request should include [authentication header](#authentication). - -## GET /account -[user-accounts-api-get-account]: #user-accounts-api-get-account - -Get information about the account attached to the current session. - -Request should include [authentication header](#authentication). - -Response body (JSON): - -``` -{ - username: String, the accounts username (required) - email: String, the accounts email (optional) - diskUsage: Number, how much disk space has the user's data taken? (optional) - diskQuota: Number, how much disk space can the user's data take? (optional) - updatedAt: Number, the Unix timestamp of the last time the user account was updated (optional) - createdAt: Number, the Unix timestamp of the last time the user account was updated (optional) -} -``` - -If `diskQuota` is not included or is set to 0, the service is acting as a "registry" and will not host the files. - - -# Dat pinning API -[dat-pinning-api]: #dat-pinning-api - -The dat pinning API should provide the following resources: - -``` -GET / List all Dat data pinned by this account. -POST /add Add a Dat to this account's list of pins. -POST /remove Remove a Dat from this account's list of pins. -GET /item/:key Get information about a Dat in the account's list of pins. -POST /item/:key Update information about a Dat in the account's list of pins. -``` - -## GET / -[dat-pinning-api-get-root]: #dat-pinning-api-get-root - -List all Dat data pinned by this account. - -Request should include [authentication header](#authentication). - -Response body (JSON): - -``` -{ - items: [{ - url: String, dat url - name: String, optional shortname assigned by the user - title: String, optional title extracted from the dat's manifest file - description: String, optional description extracted from the dat's manifest file - additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at - }] -} -``` - -## POST /add -[dat-pinning-api-post-add]: #dat-pinning-api-post-add - -Add a Dat to this account's list of pins. - -Request should include [authentication header](#authentication). -Request body (JSON): - -``` -{ - url: String, required url/key of the dat - name: String, optional shortname for the archive - domains: Array of Strings, optional list of domain-names the dat should be made available at -} -``` - -## POST /remove -[dat-pinning-api-post-remove]: #dat-pinning-api-post-remove - -Remove a Dat from this account's list of pins. - -Request should include [authentication header](#authentication). -Request body (JSON): - -``` -{ - url: String, required url/key of the dat -} -``` - -## GET /item/:key -[dat-pinning-api-get-item]: #dat-pinning-api-get-item - -Get information about a Dat in the account's list of pins. Key must be the -pubkey of the dat. - -Response body (JSON): - -``` -{ - url: String, dat url - name: String, optional shortname assigned by the user - title: String, optional title extracted from the dat's manifest file - description: String, optional description extracted from the dat's manifest file - additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at -} -``` - -## POST /item/:key -[dat-pinning-api-post-item]: #dat-pinning-api-post-item - -Update information about a Dat in the account's list of pins. Key must be the -pubkey of the dat. - -Request body (JSON): - -``` -{ - name: String, optional shortname for the archive - domains: Array of Strings, optional list of domain-names the dat should be made available at -} -``` - - -# Authentication -[authentication]: #authentication - -Clients should use the [User accounts API](#user-accounts-api) to fetch a -session token from the service. This token should be included in the -`Authentication` header using the `Bearer` scheme. - - -# Error responses -[error-responses]: #error-responses - -All error responses should respond with a JSON body which matches the -following schema: - -``` -{ - message: String -} -``` - -The content of `message` will be displayed to the user. It should explain the -error and, if appropriate, give steps for solving the issue. Other fields may -be included in the response. - - -# Rationale and alternatives -[alternatives]: #alternatives - -- The motivations and drawbacks of the PSA Service Document are discussed -[here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). -Without a description format, it becomes difficult to handle user -authentication. We would probably need to use the HTTP Basic scheme and remove -any mechanisms for registering new accounts. - - -# Unresolved questions -[unresolved]: #unresolved-questions - -- Does the registration flow need to be included in the spec? - - -# Changelog -[changelog]: #changelog - -- YYYY-MM-DD: First complete draft submitted for review - diff --git a/proposals/0003-http-pinning-service-api.md b/proposals/0003-http-pinning-service-api.md new file mode 100644 index 0000000..d113986 --- /dev/null +++ b/proposals/0003-http-pinning-service-api.md @@ -0,0 +1,277 @@ + +Title: **DEP-0003: HTTP Pinning Service API** + +Short Name: `0003-http-pinning-service-api` + +Type: Standard + +Status: Draft (as of 2018-04-18) + +Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/19) + +Authors: Paul Frazee + + +# Summary +[summary]: #summary + +An HTTP API for adding and removing Dat data. + + +# Motivation +[motivation]: #motivation + +Users frequently make use of "pinning services" to keep their Dat data online +independently of their personal devices. By specifying a standard API for +accessing pinning services, we can integrate interfaces for these services to +Dat clients (including the Dat CLI and Beaker Browser). For example, in the Dat +CLI, it will be possible to execute commands such as: + +``` +dat publish --name myarchive my-pinning-service.com +``` + + +# Service description (PSA) document +[service-description]: #service-description + +Servers should host the PSA service-description document at `/.well-known/psa`. +It may be fetched using a GET request. This document will fit the following schema: + +```json +{ + "PSA": 1, + "title": "My Pinning Service", + "description": "Keep your Dats online!", + "links": [{ + "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-account-api", + "title": "User accounts API", + "href": "/v1/accounts" + }, { + "rel": "https://archive.org/services/purl/purl/datprotocol/spec/pinning-service-dats-api", + "title": "Dat pinning API", + "href": "/v1/dats" + }] +} +``` + +You can read more about the [PSA Service Discovery +Protocol](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol). + +The PSA document must provide links to two API resources: the User Accounts +API, and the Dat Pinning API. These resources should be indicated by the +`user-accounts-api.com/v1` and `datprotocol.com/deps/0000-http-pinning-service-api` +rel-types, respectively. (These rel-types will need to be updated +with the final URLs for their specifications.) If either API is absent from +the PSA document, the service will be rejected. + + +# User accounts API +[user-accounts-api]: #user-accounts-api + +The user-accounts API should provide the following resources: + +``` +POST /login Create a new session with an existing account. +POST /logout End a session. +GET /account Get information about the account attached to the current session. +``` + +## POST /login +[user-accounts-api-post-login]: #user-accounts-api-post-login + +Create a new session with an existing account. + +Request body (JSON). All fields required: + +``` +{ + username: String + password: String +} +``` + +Handler should generate a session and return the identifier in the response. +Response body (JSON): + +``` +{ + sessionToken: String +} +``` + +## POST /logout +[user-accounts-api-post-logout]: #user-accounts-api-post-logout + +End a session. + +Request should include [authentication header](#authentication). + +## GET /account +[user-accounts-api-get-account]: #user-accounts-api-get-account + +Get information about the account attached to the current session. + +Request should include [authentication header](#authentication). + +Response body (JSON): + +``` +{ + username: String, the accounts username (required) + email: String, the accounts email (optional) + diskUsage: Number, how much disk space has the user's data taken? (optional) + diskQuota: Number, how much disk space can the user's data take? (optional) + updatedAt: Number, the Unix timestamp of the last time the user account was updated (optional) + createdAt: Number, the Unix timestamp of the last time the user account was updated (optional) +} +``` + +If `diskQuota` is not included or is set to 0, the service is acting as a "registry" and will not host the files. + + +# Dat pinning API +[dat-pinning-api]: #dat-pinning-api + +The dat pinning API should provide the following resources: + +``` +GET / List all Dat data pinned by this account. +POST /add Add a Dat to this account's list of pins. +POST /remove Remove a Dat from this account's list of pins. +GET /item/:key Get information about a Dat in the account's list of pins. +POST /item/:key Update information about a Dat in the account's list of pins. +``` + +## GET / +[dat-pinning-api-get-root]: #dat-pinning-api-get-root + +List all Dat data pinned by this account. + +Request should include [authentication header](#authentication). + +Response body (JSON): + +``` +{ + items: [{ + url: String, dat url + name: String, optional shortname assigned by the user + title: String, optional title extracted from the dat's manifest file + description: String, optional description extracted from the dat's manifest file + additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at + }] +} +``` + +## POST /add +[dat-pinning-api-post-add]: #dat-pinning-api-post-add + +Add a Dat to this account's list of pins. + +Request should include [authentication header](#authentication). +Request body (JSON): + +``` +{ + url: String, required url/key of the dat + name: String, optional shortname for the archive + domains: Array of Strings, optional list of domain-names the dat should be made available at +} +``` + +## POST /remove +[dat-pinning-api-post-remove]: #dat-pinning-api-post-remove + +Remove a Dat from this account's list of pins. + +Request should include [authentication header](#authentication). +Request body (JSON): + +``` +{ + url: String, required url/key of the dat +} +``` + +## GET /item/:key +[dat-pinning-api-get-item]: #dat-pinning-api-get-item + +Get information about a Dat in the account's list of pins. Key must be the +pubkey of the dat. + +Response body (JSON): + +``` +{ + url: String, dat url + name: String, optional shortname assigned by the user + title: String, optional title extracted from the dat's manifest file + description: String, optional description extracted from the dat's manifest file + additionalUrls: Array of Strings, optional list of URLs the dat can be accessed at +} +``` + +## POST /item/:key +[dat-pinning-api-post-item]: #dat-pinning-api-post-item + +Update information about a Dat in the account's list of pins. Key must be the +pubkey of the dat. + +Request body (JSON): + +``` +{ + name: String, optional shortname for the archive + domains: Array of Strings, optional list of domain-names the dat should be made available at +} +``` + + +# Authentication +[authentication]: #authentication + +Clients should use the [User accounts API](#user-accounts-api) to fetch a +session token from the service. This token should be included in the +`Authentication` header using the `Bearer` scheme. + + +# Error responses +[error-responses]: #error-responses + +All error responses should respond with a JSON body which matches the +following schema: + +``` +{ + message: String +} +``` + +The content of `message` will be displayed to the user. It should explain the +error and, if appropriate, give steps for solving the issue. Other fields may +be included in the response. + + +# Rationale and alternatives +[alternatives]: #alternatives + +- The motivations and drawbacks of the PSA Service Document are discussed +[here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). +Without a description format, it becomes difficult to handle user +authentication. We would probably need to use the HTTP Basic scheme and remove +any mechanisms for registering new accounts. + + +# Unresolved questions +[unresolved]: #unresolved-questions + +- Does the registration flow need to be included in the spec? + + +# Changelog +[changelog]: #changelog + + - 2018-03-31: First full draft of DEP-0003 submitted for review. + - 2018-04-18: DEP-0003 accepted as "Draft" + -- cgit v1.2.3 From 1710d82d0554deaf2926719ec0d08b3424c28e5c Mon Sep 17 00:00:00 2001 From: Paul Frazee Date: Wed, 18 Apr 2018 12:41:26 -0500 Subject: Use archived links to PSA spec --- proposals/0003-http-pinning-service-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/0003-http-pinning-service-api.md b/proposals/0003-http-pinning-service-api.md index d113986..d3d9328 100644 --- a/proposals/0003-http-pinning-service-api.md +++ b/proposals/0003-http-pinning-service-api.md @@ -56,7 +56,7 @@ It may be fetched using a GET request. This document will fit the following sche ``` You can read more about the [PSA Service Discovery -Protocol](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol). +Protocol](http://web.archive.org/web/20180418164539/https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol). The PSA document must provide links to two API resources: the User Accounts API, and the Dat Pinning API. These resources should be indicated by the @@ -257,7 +257,7 @@ be included in the response. [alternatives]: #alternatives - The motivations and drawbacks of the PSA Service Document are discussed -[here](https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). +[here](http://web.archive.org/web/20180418164539/https://github.com/beakerbrowser/beaker/wiki/PSA-Web-Service-Discovery-Protocol#motivation). Without a description format, it becomes difficult to handle user authentication. We would probably need to use the HTTP Basic scheme and remove any mechanisms for registering new accounts. -- cgit v1.2.3