diff options
Diffstat (limited to 'proposals/0000-http-pinning-service-api.md')
| -rw-r--r-- | proposals/0000-http-pinning-service-api.md | 205 |
1 files changed, 205 insertions, 0 deletions
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 + |