aboutsummaryrefslogtreecommitdiffstats
path: root/proposals/0000-http-pinning-service-api.md
diff options
context:
space:
mode:
Diffstat (limited to 'proposals/0000-http-pinning-service-api.md')
-rw-r--r--proposals/0000-http-pinning-service-api.md150
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