Ind.ie is now Small Technology Foundation.
Commit 94b04332 authored by Aral Balkan's avatar Aral Balkan

Update API and deployment documentation

(To reflect that the owner settings object in the Site Service’s create/POST call only contains the owner’s secret sign up code.)
parent d8fc54e3
......@@ -3,9 +3,9 @@ title: "API"
weight: 10
---
All API calls require the passing of a secret that authenticates them. For the test server, this secret is hardcoded.
All API calls require the passing of a cryptographically-secure shared secret access token to authenticate them. The secret access token is communicated out of band via a cryptographically secure channel between Hallo.gent (Smart Citizen Lab at Stad Gent) and the Magic Website Factory (Combell). For the test server, a mock secret access token is hardcoded.
`secret = "<secret>"`
All communication is over TLS (HTTPS) only. Server setups on both ends have HTTP access disabled.
## API versioning
......@@ -28,21 +28,21 @@ Check if the domain is available. Returns a JSON object with a boolean status.
#### Parameters
`/domain/<domain>?secret=<secret>`
`/domain/<domain>?secret=<secret-access-token>`
Where the following known values for `domain` returns the following responses:
#### Responses
* available.gent: `{"status": true}`
* unavailable.gent: `{"status": false}`
* error.gent: triggers the 503 service unavailable error.
* Domain available: `{"available": true}`
* Domain not available: `{"available": false}`
* Domain check service not functional/available: 503 Service Unavailable error.
On error, the server should return a valid error message.
On the testing servers, the following known values for `domain` returns the following responses:
Valid errors:
* 503: Service unavailable. The domain check/registration service is unavailable.
* available.gent: `{"available": true}`
* unavailable.gent: `{"available": false}`
* error.gent: 503 Service Unavailable error.
## Site service
......@@ -52,18 +52,16 @@ Location: `/site`
Asks for the passed domain to be registered and for an Indie Site to be set up at it.
#### Parameters
#### Parameters (Body; JSON)
```json
{
"domain": "<the domain to register (string)>",
"callback": "<callback URL>",
"owner-settings": {
// Object with owner settings, to be copied
// into the ~/indie/v1/owner-settings.json file
// at deployment time.
"secretSignUpCode": "<secret-sign-up-code>"
},
"secret": "<secret>"
"secret": "<secret-access-token>"
}
```
......@@ -85,11 +83,13 @@ Location: `<callback-url>/site/`
* `<callback-url>/site/<domain>`: domain to update the status for
* `?status=<code>`: 201 = created, 409 = conflict (domain not available), 500 = internal server error (the site setup process failed and will not be retried)
* `&secret=<secret>`
* `&secret=<secret-access-token>`
#### Responses
The Magic Website Factory expects the following responses to its callback request:
* 200 OK: Response successfully received
* Error code (depending on error): callback failed. Log the error and queue the callback to be tried again (exponential falloff).
\ No newline at end of file
* Error code (depending on error): callback failed. Log the error and queue the callback to be tried again (exponential falloff).
(When a 200 OK response is received, Hallo.gent POSTs the full owner settings, along with the secret sign-up code to the Indie Site. The Indie Site will then prompt for password creation and complete its configuration.)
......@@ -23,13 +23,29 @@ Here, we present the requirements for Indie Site configuration.
## Configuration
Indie Site expects its configuration data to be accessible from the following directory, which must be set up by the Magic Website Factory.
Indie Site expects its configuration data to be accessible from the following directory, which must be set up by the Magic Website Factory:
`~/indie/v1/`
```bash
~/indie
```
Inside that directory, it expects the following file:
`owner-settings.json`: the owner settings that were passed to the [Magic Website Factory Site Service (POST) method](../api/#site-service)
```bash
~/indie/owner-settings.json
```
The `owner-settings.json` file contains the owner settings that were passed to the [Magic Website Factory Site Service (POST) method](../api/#site-service)
The owner settings object that is passed only contains the `<secret sign-up code>`, so the _~/indie/owner-settings.json_ in a configured Indie Site instance should match the following:
```json
{
"secretSignupCode": "<secret-sign-up-code>"
}
```
Indie Site uses the `secretSignupCode` to authenticate the initial configuration call from Hallo.gent. Unless the secret sign-up code passed matches the one in _~/indie/owner-settings.json_, attempts to configure the new site are refused. This is to prevent an edge-case where a malicious actor might gain access and ownership of newly-created Indie Sites before the legitimate owner has had a chance to set up their password and claim ownership.
## Running
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment