diff options
| -rw-r--r-- | proposals/0000-http-pinning-service-api.md | 150 |
1 files 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 |