172 lines
6.3 KiB
Markdown
172 lines
6.3 KiB
Markdown
# API
|
|
The API system is intended for use with Desktop and Mobile clients.
|
|
It must be accessed using one of the following domains as the Host header:
|
|
|
|
* localhost.alpha.daplie.me
|
|
* localhost.admin.daplie.me
|
|
* alpha.localhost.daplie.me
|
|
* admin.localhost.daplie.me
|
|
* localhost.daplie.invalid
|
|
|
|
All requests require an OAuth3 token in the request headers.
|
|
|
|
## Tokens
|
|
|
|
Some of the functionality of goldilocks requires the use of OAuth3 tokens to
|
|
perform tasks like setting DNS records. Management of these tokens can be done
|
|
using the following APIs.
|
|
|
|
### Get A Single Token
|
|
* **URL** `/api/goldilocks@daplie.com/tokens/:id`
|
|
* **Method** `GET`
|
|
* **Reponse**: The token matching the specified ID. Has the following properties.
|
|
* `id`: The hash used to identify the token. Based on several of the fields
|
|
inside the decoded token.
|
|
* `provider_uri`: The URI for the one who issued the token. Should be the same
|
|
as the `iss` field inside the decoded token.
|
|
* `client_uri`: The URI for the app authorized to use the token. Should be the
|
|
same as the `azp` field inside the decoded token.
|
|
* `scope`: The list of permissions granted by the token. Should be the same
|
|
as the `scp` field inside the decoded token.
|
|
* `access_token`: The encoded JWT.
|
|
* `token`: The decoded token.
|
|
|
|
### Get All Tokens
|
|
* **URL** `/api/goldilocks@daplie.com/tokens`
|
|
* **Method** `GET`
|
|
* **Reponse**: An array of the tokens stored. Each item looks the same as if it
|
|
had been requested individually.
|
|
|
|
### Save New Token
|
|
* **URL** `/api/goldilocks@daplie.com/tokens`
|
|
* **Method** `POST`
|
|
* **Body**: An object similar to an OAuth3 session used by the javascript
|
|
library. The only important fields are `refresh_token` or `access_token`, and
|
|
`refresh_token` will be used before `access_token`. (This is because the
|
|
`access_token` usually expires quickly, making it meaningless to store.)
|
|
* **Reponse**: The response looks the same as a single GET request.
|
|
|
|
### Delete Token
|
|
* **URL** `/api/goldilocks@daplie.com/tokens/:id`
|
|
* **Method** `DELETE`
|
|
* **Reponse**: Either `{"success":true}` or `{"success":false}`, depending on
|
|
whether the token was present before the request.
|
|
|
|
## Config
|
|
|
|
### Get All Settings
|
|
* **URL** `/api/goldilocks@daplie.com/config`
|
|
* **Method** `GET`
|
|
* **Reponse**: The JSON representation of the current config. See the [README.md](/README.md)
|
|
for the structure of the config.
|
|
|
|
### Get Group Setting
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group`
|
|
* **Method** `GET`
|
|
* **Reponse**: The sub-object of the config relevant to the group specified in
|
|
the url (ie http, tls, tcp, etc.)
|
|
|
|
### Get Group Module List
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group/modules`
|
|
* **Method** `GET`
|
|
* **Reponse**: The list of modules relevant to the group specified in the url
|
|
(ie http, tls, tcp, etc.)
|
|
|
|
### Get Specific Module
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group/modules/:modId`
|
|
* **Method** `GET`
|
|
* **Reponse**: The module with the specified module ID.
|
|
|
|
### Get Domain Group
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId`
|
|
* **Method** `GET`
|
|
* **Reponse**: The domains specification with the specified domains ID.
|
|
|
|
### Get Domain Group Modules
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules`
|
|
* **Method** `GET`
|
|
* **Reponse**: An object containing all of the relevant modules for the group
|
|
of domains.
|
|
|
|
### Get Domain Group Module Category
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules/:group`
|
|
* **Method** `GET`
|
|
* **Reponse**: A list of the specific category of modules for the group of domains.
|
|
|
|
### Get Specific Domain Group Module
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules/:group/:modId`
|
|
* **Method** `GET`
|
|
* **Reponse**: The module with the specified module ID.
|
|
|
|
|
|
### Change Settings
|
|
* **URL** `/api/goldilocks@daplie.com/config`
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group`
|
|
* **Method** `POST`
|
|
* **Body**: The changes to be applied on top of the current config. See the
|
|
[README.md](/README.md) for the settings. If modules or domains are specified
|
|
they are added to the current list.
|
|
* **Reponse**: The current config. If the group is specified in the URL it will
|
|
only be the config relevant to that group.
|
|
|
|
### Add Module
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group/modules`
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules/:group`
|
|
* **Method** `POST`
|
|
* **Body**: The module to be added. Can also be provided an array of modules
|
|
to add multiple modules in the same request.
|
|
* **Reponse**: The current list of modules.
|
|
|
|
### Add Domain Group
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains`
|
|
* **Method** `POST`
|
|
* **Body**: The domains names and modules for the new domain group(s).
|
|
* **Reponse**: The current list of domain groups.
|
|
|
|
|
|
### Edit Module
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group/modules/:modId`
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules/:group/:modId`
|
|
* **Method** `PUT`
|
|
* **Body**: The new parameters for the module.
|
|
* **Reponse**: The editted module.
|
|
|
|
### Edit Domain Group
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId`
|
|
* **Method** `PUT`
|
|
* **Body**: The new domains names for the domains group. The module list cannot
|
|
be editted through this route.
|
|
* **Reponse**: The editted domain group.
|
|
|
|
|
|
### Remove Module
|
|
* **URL** `/api/goldilocks@daplie.com/config/:group/modules/:modId`
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId/modules/:group/:modId`
|
|
* **Method** `DELETE`
|
|
* **Reponse**: The list of modules.
|
|
|
|
### Remove Domain Group
|
|
* **URL** `/api/goldilocks@daplie.com/config/domains/:domId`
|
|
* **Method** `DELETE`
|
|
* **Reponse**: The list of domain groups.
|
|
|
|
|
|
## Socks5 Proxy
|
|
|
|
### Check Status
|
|
* **URL** `/api/goldilocks@daplie.com/socks5`
|
|
* **Method** `GET`
|
|
* **Response**: The returned object will have up to two values inside
|
|
* `running`: boolean value to indicate if the proxy is currently active
|
|
* `port`: if the proxy is running this is the port it's running on
|
|
|
|
### Start Proxy
|
|
* **URL** `/api/goldilocks@daplie.com/socks5`
|
|
* **Method** `POST`
|
|
* **Response**: Same response as for the `GET` request
|
|
|
|
### Stop Proxy
|
|
* **URL** `/api/goldilocks@daplie.com/socks5`
|
|
* **Method** `DELETE`
|
|
* **Response**: Same response as for the `GET` request
|