Finish first draft of 0000-http-pinning-service-api.md

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