chore: Port FreeSewing.dev to docusaurus
The replaces the NextJS site powering FreeSewing.dev with a Docusaurus setup. It's part of my efforts to simplify FreeSewing's setup so we can focus on our core value proposition.
This commit is contained in:
Joost De Cock
parent
497633d1d3
commit
ab3204f9f1
692 changed files with 11037 additions and 20674 deletions
|
|
@ -1,97 +0,0 @@
|
|||
---
|
||||
title: Create an API key
|
||||
---
|
||||
|
||||
Creates a new API key. An API key can be used to authenticate against the
|
||||
backend API.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/rbac) `4` or higher is required to create an API key
|
||||
|
||||
## Endpoints
|
||||
|
||||
Creating a new API key is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method post /> | `/apikeys/jwt` | [JSON Web Token](/reference/backend/authentication#jwt-authentication) |
|
||||
| <Method post /> | `/apikeys/key` | [API Key & Secret](/reference/backend/authentication#key-authentication) |
|
||||
|
||||
## Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `name` | `string` | A name for the API key |
|
||||
| `level` | `number` | A privilege level from 0 to 8. |
|
||||
| `expiresIn` | `number` | The number of seconds until the API key expires |
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="201"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | the request lacks authentication |
|
||||
| <StatusCode status="403"/> | authentication failed |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="201" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
## Response body
|
||||
|
||||
<Warning>
|
||||
##### Make sure to save the secret
|
||||
The response body is the only time the API key's secret will be revealed.
|
||||
</Warning>
|
||||
|
||||
| Value | Type | Description |
|
||||
| ------------------- | -------- | ----------- |
|
||||
| `result` | `string` | Either `success` or `error` |
|
||||
| `error` | `string` | Will give info on the nature of the error. Only set if an error occurred. |
|
||||
| `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 |
|
||||
|
||||
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const apiKey = axios.post(
|
||||
'https://backend.freesewing.org/apikeys/jwt',
|
||||
{
|
||||
name: 'My first API key',
|
||||
level: 2, // Read only
|
||||
expiresIn: 3600, // One hour
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```201.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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
---
|
||||
title: Delete an API key
|
||||
---
|
||||
|
||||
Deletes an existing API key.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/rbac) `4` or higher is required to delete an API key
|
||||
|
||||
## Endpoints
|
||||
|
||||
Deleting an API key is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method delete /> | `/apikeys/:id/jwt` | [JSON Web Token](/reference/backend/authentication#jwt-authentication) |
|
||||
| <Method delete /> | `/apikeys/:id/key` | [API Key & Secret](/reference/backend/authentication#key-authentication) |
|
||||
|
||||
## Request URL
|
||||
|
||||
The URL should contain the ID of the API key you wish to remove.
|
||||
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="204"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | the request lacks authentication |
|
||||
| <StatusCode status="403"/> | authentication failed |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
await axios.delete(
|
||||
'https://backend.freesewing.org/apikeys/7ea12968-7758-40b6-8c73-75cc99be762b/jwt',
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
|
||||
```204.json
|
||||
```
|
||||
<Note>
|
||||
These endpoints return status code <StatusCode status="204"/> (no content) on
|
||||
success, with no response body.
|
||||
</Note>
|
||||
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
---
|
||||
title: API Keys
|
||||
---
|
||||
|
||||
API keys are a way to authenticate to the API with basic authentication.
|
||||
They are intended to be used when interacting with the API in an automated
|
||||
way such as from a script or a CI/CD pipeline.
|
||||
|
||||
They are an alternative to JSON Web Tokens (JWT) which is typically used
|
||||
to authenticate users in a browser session.
|
||||
|
||||
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](/reference/backend/authentication).
|
||||
|
||||
## Endpoints
|
||||
|
||||
<ReadMore />
|
||||
|
||||
## Notes
|
||||
|
||||
The following is good to keep in mind when working with API keys:
|
||||
|
||||
### 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 a 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>
|
||||
|
||||
|
|
@ -1,81 +0,0 @@
|
|||
---
|
||||
title: Read an API key
|
||||
---
|
||||
|
||||
Reads an existing API key. Note that the API secret can only be retrieved at
|
||||
the moment the API key is created.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/rbac) `4` or higher is required to read an API key
|
||||
|
||||
## Endpoints
|
||||
|
||||
Reading an API key is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method get /> | `/apikeys/:id/jwt` | [JSON Web Token](/reference/backend/authentication#jwt-authentication) |
|
||||
| <Method get /> | `/apikeys/:id/key` | [API Key & Secret](/reference/backend/authentication#key-authentication) |
|
||||
|
||||
## Request URL
|
||||
|
||||
The URL should contain the ID of the API key you wish to remove.
|
||||
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="200"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | the request lacks authentication |
|
||||
| <StatusCode status="403"/> | authentication failed |
|
||||
| <StatusCode status="404"/> | API key not found |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
## Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| ------------------- | -------- | ----------- |
|
||||
| `result` | `string` | `success` on success, and `error` on error |
|
||||
| `error` | `string` | Will give info on the nature of the error. Only set if an error occurred. |
|
||||
| `apikey.key` | `string` | The API key |
|
||||
| `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 |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const keyInfo = await axios.get(
|
||||
'https://backend.freesewing.org/apikeys/7ea12968-7758-40b6-8c73-75cc99be762b/jwt',
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"apikey": {
|
||||
"key": "7ea12968-7758-40b6-8c73-75cc99be762b",
|
||||
"level": 3,
|
||||
"expiresAt": "2022-11-06T15:57:30.190Z",
|
||||
"name": "My first API key",
|
||||
"userId": 61
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -1,73 +0,0 @@
|
|||
---
|
||||
title: Read the current API key
|
||||
---
|
||||
|
||||
Reads the current API key used to authenticate the request.
|
||||
For obvious reasons, this endpoint is only available with API key authentication.
|
||||
However, there's an equivalent endpoint for JWT authentication.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/rbac) `0` or higher is required to read the current API key
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method get /> | `/whoami/key` | [API Key & Secret](/reference/backend/authentication#key-authentication) |
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="200"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | the request lacks authentication |
|
||||
| <StatusCode status="403"/> | authentication failed |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
## Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| ------------------- | -------- | ----------- |
|
||||
| `result` | `string` | `success` on success, and `error` on error |
|
||||
| `error` | `string` | Will give info on the nature of the error. Only set if an error occurred. |
|
||||
| `apikey.key` | `string` | The API key |
|
||||
| `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 |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const keyInfo = await axios.get(
|
||||
'https://backend.freesewing.org/whoami/key',
|
||||
{
|
||||
auth: {
|
||||
username: apikey.key,
|
||||
password: apikey.secret,
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"apikey": {
|
||||
"key": "7ea12968-7758-40b6-8c73-75cc99be762b",
|
||||
"level": 3,
|
||||
"expiresAt": "2022-11-06T15:57:30.190Z",
|
||||
"name": "My first API key",
|
||||
"userId": 61
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue