VSinerva/freesewing
1
0
Fork 0
Code Activity

wip(backend): more work on routes and docs

Browse source
This commit is contained in:
joostdecock 2022-11-06 17:39:49 +01:00
parent 3fc08d8bdb
commit d563bb2d17
10 changed files with 349 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

134
markdown/dev/reference/backend/api/apikey/en.md Normal file
View file

@ -0,0 +1,134 @@
---
title: API Keys
---
Documentation for the REST API endpoints to create, read, or remove API keys.
<Tip>
The FreeSewing backend REST API supports authentication both with JSON Web
Tokens (JWT) as with API keys (KEY). This describes the endpoints that deal
with creating, reading, and removing API keys. For authentication details,
refer to [the section on authenticating to the
API](/reference/backend/api#authentication).
</Tip>
## Create a new API key
Create a new API key. The API key will belong to the user who is authenticated
when making the call. Supported for both JWT and KEY authentication.
### Endpoints
| Method | Path | Description |
| ------ | ---- | ----------- |
| `POST` | `/apikey/jwt` | Create a new API key. Endpoint for JWT authentication |
| `POST` | `/apikey/key` | Create a new API key. Endpoint for API key authentication |
### Parameters
<Tabs tabs="Request, Response">
<Tab>
| Variable | Type | Description |
| -------- | -------- | ----------- |
| `name` | `string` | Create a new API key. Endpoint for JWT authentication |
| `level` | `number` | A privilege level from 0 to 8. |
| `expiresIn` | `number` | The number of seconds until this key expires. |
</Tab>
<Tab>
Returns status code `200` on success, `400` on if the request is malformed, and
`500` on server error.
| Value | Type | Description |
| ------------------- | -------- | ----------- |
| `result` | `string` | `success` on success, and `error` on error |
| `apikey.key` | `string` | The API key |
| `apikey.secret` | `string` | The API secret |
| `apikey.level` | `number` | The privilege level of the API key |
| `apikey.expiresAt` | `string` | A string representation of the moment the API key expires |
| `apikey.name` | `string` | The name of the API key |
| `apikey.userId` | `number` | The ID of the user who created the API key |
</Tab>
</Tabs>
### Example
<Tabs tabs="Request, Response">
<Tab>
```js
const token = axios.post(
'https://backend.freesewing.org/apikey/jwt',
{
name: 'My first API key',
level: 2, // Read only
expiresIn: 3600, // One hour
},
{
headers: {
Authorization: `Bearer ${token}`
}
}
)
```
</Tab>
<Tab>
```json
{
result: 'success',
apikey: {
key: '7ea12968-7758-40b6-8c73-75cc99be762b',
secret: '503d7adbdb3ec18ab27adfcd895d8b47a8d6bc8307d548500fbf9c05a5a8820e',
level: 3,
expiresAt: '2022-11-06T15:57:30.190Z',
name: 'My first API key',
userId: 61
}
}
```
</Tab>
</Tabs>
## Notes
The following is good to keep in mind when working with API keys:
### This is not the authentication documentation
The FreeSewing backend REST API supports authentication both with JSON Web
Tokens (JWT) as with API keys (KEY).
This describes the endpoints that deal with creating, reading, and removing API
keys. For authentication details, refer to [the section on authenticating to
the API](/reference/backend/api#authentication).
### API keys are immutable
Once created, API keys cannot be updated.
You should remove them and re-create a new one if you want to make change.
### API keys have an expiry
API keys have an expiry date. The maximum validity for an API key is 1 year.
### API keys have a permission level
API keys have a permission level. You can never create an API key with a higher
permission level than your own permission level.
### Circumstances that will trigger your API keys to be revoked
As a precaution, all your API keys will be revoked when:
- Your role is downgraded to a role with fewer privileges
- Your account is (b)locked
- You revoke your consent for FreeSewing to process your data
<Note>
This is not an exhaustive list. For example, if we find your use of our API to
be excessive, we might also revoke your API keys to shield us from the
financial impact of your use of our API.
</Note>

104
markdown/dev/reference/backend/api/en.md Normal file
View file

@ -0,0 +1,104 @@
---
title: REST API
---
This is the reference documentation for the FreeSewing backend REST API.
<Fixme>
This documentation is under construction as we are re-working this API for v3.
</Fixme>
## Purpose of this API
This API is how one can interact with the FreeSewing backend data.
That means the data for our users, including all people they have added to
their profile, as well as all of the patterns they have saved to our profile.
This API also manages subscriptions to our newsletter, and a number of other
automation tasks such as creating issues on Github.
## Authentication
This API is not accessible without authentication.
The FreeSewing backend API allows two types of authentication:
- JSON Web Tokens (jwt): This is typically used to authenticate humans in a
browser session.
- API Keys (key): This is typically used to interact with the API in an
automated way. Like in a script, or a CI/CD context.
Apart from the handlful of API endpoints that are accessible without
authentication (typically the ones dealing with the signup flow), this API has
a variant for each route depending on what authentication you want to use:
- `/some/route/jwt` : Authenticate with JWT
- `/some/route/key` : Authenticate with an API key and secret
### JWT authentication
The use of JSON Web Tokens ([jwt](https://jwt.io)) is typically used in a browser context where we want to establish a *session*.
To get a token, you must first authenticate at the `/login` endpoint with username and password.
You will receive a token in the response.
In subsequent API calls, you must then include this token in the `Authorization` header prefixed by `Bearer`. Liek his:
```js
const account = await axios.get(
`https://backend.freesewing.org/account/jwt`,
{
headers: {
Authorization: `Bearer ${token}`
}
}
)
```
### API key authentication
The combination API key & secret serves as a username & password for HTTP basic authentication.
In basic authentication, the password is sent unencrypted, but since the FreeSewing backend is only reachable over a TLS encrypted connection, this is not a problem.
On the plus side, sending a username and password with a request is supported pretty much everywhere.
In addition, there is no need to establish a session first, so this make the entire transation stateless.
Below is an example using curl:
```sh
curl -u api-key-here:api-secret-here \
https://backend.freesewing.org/account/key
```
## Privilege levels for user roles and API keys
The privilege level is an intiger from `0` to `8`. The higher the number, the higher the priviledge.
User accounts have a `role` that determines their privilege level.
The available roles (with their privilege levels) are:
- **user**: `4`
- **bughunter**: `5`
- **support**: `6`
- **admin**: `8`
These roles are used when using JWT authentication, as that's typically used by humans.
When using API keys, the privilege level can be set on the API key itself in a more granular way.
The table below lists the priviledge of all levels as well as their corresponding <small><small><b>`role`</b></small></small>:
| Level | Abilities | <small><small>`user`</small></small> | <small><small>`bughunter`</small></small> | <small><small>`support`</small></small> | <small><small>`admin`</small></small> |
| --: | -- | :--: | :--: | :--: | :--: |
| `0` | authenticate | ✅ | ✅ | ✅ | ✅ |
| `1` | **read** measurements and patterns | ✅ | ✅ | ✅ | ✅ |
| `2` | **read all** account data | ✅ | ✅ | ✅ | ✅ |
| `3` | **write** measurements or patterns | ✅ | ✅ | ✅ | ✅ |
| `4` | **write all** account data | ✅ | ✅ | ✅ | ✅ |
| `5` | **read** measurements or patterns of **other users** | ❌ | ✅ | ✅ | ✅ |
| `6` | **read all** account data of **other users** | ❌ | ❌ | ✅ | ✅ |
| `7` | **write** access through **specific support methods** | ❌ | ❌ | ✅ | ✅ |
| `8` | impersonate other user, full write access | ❌ | ❌ | ❌ | ✅ |
## API Routes
<ReadMore />