VSinerva/freesewing
1
0
Fork 0
Code Activity

Merge pull request #3112 from darigovresearch/patch-4

Browse source 
fix: More copy updates to backend api docs
This commit is contained in:
Joost De Cock 2022-12-03 16:40:02 +01:00 • committed by GitHub
commit 4cc9471929
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 58 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

6
markdown/dev/reference/backend/api/account/confirm/en.md
View file

@ -15,9 +15,9 @@ Confirming a new User account is possible via this endpoint:
<Note compact>This endpoint requires no authentication</Note>
## Request url
## Request URL
The url should contain the confirmation ID that was E-mailed to the E-mail
The URL should contain the confirmation ID that was E-mailed to the E-mail
address used for the signup. It replaces the `:id` placeholder in the
[endpoint listed above](#endpoints).
@ -56,7 +56,7 @@ in the response body should indicate the nature of the problem.
| `account.control` | Number | The control desired by the User |
| `account.createdAt` | String | Date string indicating the moment the User was created |
| `account.email` | String | The E-mail address currently tied to the User |
| `account.github` | String | The Github username of the User |
| `account.github` | String | The GitHub username of the User |
| `account.img` | String | The URL to the image stored with this User |
| `account.imperial` | Boolean| Whether or not the User prefers imperial units |
| `account.initial` | String | The E-mail address that the User was created with |

4
markdown/dev/reference/backend/api/account/create/en.md
View file

@ -2,7 +2,7 @@
title: Create an account
---
Creates a new User account. The User account will remain inactive
Creates a new User account. The User account will remain inactive
until [it is confirmed](/reference/backend/api/account/confirm).
## Endpoints
@ -42,7 +42,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `email` | String | The E-mail address where the confirmation email was sent to |
## Example request

6
markdown/dev/reference/backend/api/account/en.md
View file

@ -59,7 +59,7 @@ hash the email provided to us, and search the hash instead.
The `ehash` and `ihash` fields hold the hash for the `email` and `initial`
fields.
### The `imperial` property is a boolean
### The `imperial` property is a Boolean
If the `imperial` property is `false`, the user wants metric units.
@ -78,10 +78,10 @@ associated with the account was changed.
For the backend users `Joost` and `joost` are -- strictly speaking -- two
different users. This tends to lead to confusion and possible impersonation.
So we enforce uniquness on the `lusername` field which holds a lowercased
So we enforce uniqueness on the `lusername` field which holds a lowercased
version of the `username` field..
In other words, lowercased usernamed must be uique.
In other words, lowercased username must be unique.
### The `status` field holds the account status

4
markdown/dev/reference/backend/api/account/login/en.md
View file

@ -46,7 +46,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `token` | String | A JSON web token (JWT) token to authenticate with |
| `account.id` | Number | The ID of the User |
| `account.bio` | String | The bio of the User |
@ -54,7 +54,7 @@ in the response body should indicate the nature of the problem.
| `account.control` | Number | The control desired by the User |
| `account.createdAt` | String | Date string indicating the moment the User was created |
| `account.email` | String | The E-mail address currently tied to the User |
| `account.github` | String | The Github username of the User |
| `account.github` | String | The GitHub username of the User |
| `account.img` | String | The URL to the image stored with this User |
| `account.imperial` | Boolean| Whether or not the User prefers imperial units |
| `account.initial` | String | The E-mail address that the User was created with |

15
markdown/dev/reference/backend/api/account/mfa/en.md
View file

@ -47,10 +47,10 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `mfa.secret` | String | The shared secret for generating one-time password (OTP) tokens |
| `mfa.otpauth` | String | The OTP Auth uri that is encoded in the QR code |
| `mfa.qrcode` | String | SVG to display a QR code with the otpauth uri encoded |
| `mfa.otpauth` | String | The OTP Auth URI that is encoded in the QR code |
| `mfa.qrcode` | String | SVG to display a QR code with the otpauth URI encoded |
<Tip>
##### Styling the SVG
@ -119,7 +119,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
### Example request
@ -128,7 +128,7 @@ import { authenticator } from '@otplib/preset-default'
const confirm = await axios.post(
'https://backend.freesewing.org/account/mfa/jwt',
{
{
mfa: true,
secret: mfa.secret,
token: authenticator.generate(mfa.secret)
@ -182,7 +182,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
### Example request
@ -191,7 +191,7 @@ import { authenticator } from '@otplib/preset-default'
const confirm = await axios.post(
'https://backend.freesewing.org/account/mfa/jwt',
{
{
mfa: false,
password: "I like big bewbs and I just can't lie",
token: authenticator.generate(mfa.secret)
@ -211,4 +211,3 @@ const confirm = await axios.post(
"result": "success",
}
```

6
markdown/dev/reference/backend/api/account/update/en.md
View file

@ -25,7 +25,7 @@ Updating an existing User account is possible via these endpoints:
| `bio` | `string` | The User's bio |
| `consent` | `string` | A number that indicates [the consent given by the user](/reference/backend/api/account#the-consent-field-is-about-data-protection) |
| `control` | `string` | A number that indicates [the level of control the user prefers](/reference/backend/api/account#the-control-field-is-about-keeping-it-simple) |
| `github` | `string` | The User's username on Github |
| `github` | `string` | The User's username on GitHub |
| `imperial` | `boolean`| Whether or not the User prefers imperial units |
| `newsletter`| `boolean`| Whether this Person prefers imperial measurements (`true`) or not (`false`) |
| `img` | `string` | An image [data-uri][duri] to store with this Person |
@ -54,14 +54,14 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `account.id` | Number | The ID of the User |
| `account.bio` | String | The bio of the User |
| `account.consent` | Number | The consent given by the User |
| `account.control` | Number | The control desired by the User |
| `account.createdAt` | String | Date string indicating the moment the User was created |
| `account.email` | String | The E-mail address currently tied to the User |
| `account.github` | String | The Github username of the User |
| `account.github` | String | The GitHub username of the User |
| `account.img` | String | The URL to the image stored with this User |
| `account.imperial` | Boolean| Whether or not the User prefers imperial units |
| `account.initial` | String | The E-mail address that the User was created with |

4
markdown/dev/reference/backend/api/apikeys/delete/en.md
View file

@ -17,9 +17,9 @@ Deleting an API key is possible via these endpoints:
| <Method delete /> | `/apikeys/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method delete /> | `/apikeys/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the API key you wish to remove.
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

10
markdown/dev/reference/backend/api/authentication/en.md
View file

@ -2,7 +2,7 @@
title: Authentication
---
The FreeSewing backend API requires authentication for all but a handfull of
The FreeSewing backend API requires authentication for all but a handful of
endpoints.
The API supports two different types of authentication:
@ -48,17 +48,17 @@ basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
<Note>
In basic authentication, the password is sent
unencrypted. To guard against this, this API should only be served over a
connection that is encrypted with TLS. (a url starting with `https://`).
unencrypted. To guard against this, this API should only be served over a
connection that is encrypted with TLS. (a URL starting with `https://`).
</Note>
Sending a username and password with a request like this is supported
pretty much everywhere. In addition, there is no need to establish a session
first, so this make the entire transation stateless.
first, so this make the entire transaction stateless.
Below is an example using curl:
```sh
curl -u api-key-here:api-secret-here \
curl -u api-key-here:api-secret-here \
https://backend.freesewing.org/account/key
```

7
markdown/dev/reference/backend/api/patterns/clone/en.md
View file

@ -28,9 +28,9 @@ Creating a new Person is possible via these endpoints:
| <Method post /> | `/patterns/:id/clone/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method post /> | `/patterns/:id/clone/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Pattern you wish to remove.
The URL should contain the ID of the Pattern you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Response status codes
@ -55,7 +55,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `pattern.id` | Number | The ID of the Pattern |
| `pattern.createdAt` | String | Date string indicating the moment the pattern was created |
| `pattern.data` | Object | Any additional data that was stored with Pattern data |
@ -107,4 +107,3 @@ const clone = axios.post(
}
}
```

2
markdown/dev/reference/backend/api/patterns/create/en.md
View file

@ -52,7 +52,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `pattern.id` | Number | The ID of the Pattern |
| `pattern.createdAt` | String | Date string indicating the moment the pattern was created |
| `pattern.data` | Object | Any additional data that was stored with Pattern data |

5
markdown/dev/reference/backend/api/patterns/delete/en.md
View file

@ -18,9 +18,9 @@ Deleting a Pattern is possible via these endpoints:
| <Method delete /> | `/patterns/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method delete /> | `/patterns/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Pattern you wish to remove.
The URL should contain the ID of the Pattern you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Response status codes
@ -56,4 +56,3 @@ await axios.delete(
These endpoints return status code <StatusCode status="204"/> (no content) on
success, with no response body.
</Note>

3
markdown/dev/reference/backend/api/patterns/en.md
View file

@ -24,11 +24,10 @@ Keep in mind that:
- The `notes` property is intended to be used by the user to add notes about
their pattern. It will only accept data of type `string`.
- The `data` property is intended to allow frontend developers to store
additional data about the pattern. It wil only accept data of type `object`.
additional data about the pattern. It will only accept data of type `object`.
### The `settings` property should hold the pattern settings
The `settings` property should hold [a settings object](/reference/settings)
that can be passed to [the Pattern
constructor](/reference/api/pattern#creating-a-pattern).

8
markdown/dev/reference/backend/api/patterns/read/en.md
View file

@ -2,7 +2,7 @@
title: Read a Pattern
---
Reads an existing Pattern.
Reads an existing Pattern.
## Access control
@ -28,9 +28,9 @@ Reading a Pattern is possible via these endpoints:
| <Method get /> | `/patterns/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method get /> | `/patterns/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Pattern you wish to read.
The URL should contain the ID of the Pattern you wish to read.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Response status codes
@ -56,7 +56,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `pattern.id` | Number | The ID of the Pattern |
| `pattern.createdAt` | String | Date string indicating the moment the pattern was created |
| `pattern.data` | Object | Any additional data that was stored with Pattern data |

6
markdown/dev/reference/backend/api/patterns/update/en.md
View file

@ -18,9 +18,9 @@ Updating an existing Pattern is possible via these endpoints:
| <Method put /> | `/patterns/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method put /> | `/patterns/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Pattern you wish to remove.
The URL should contain the ID of the Pattern you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Request body
@ -57,7 +57,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `pattern.id` | Number | The ID of the Pattern |
| `pattern.createdAt` | String | Date string indicating the moment the pattern was created |
| `pattern.data` | Object | Any additional data that was stored with Pattern data |

7
markdown/dev/reference/backend/api/people/clone/en.md
View file

@ -28,9 +28,9 @@ Creating a new Person is possible via these endpoints:
| <Method post /> | `/people/:id/clone/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method post /> | `/people/:id/clone/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Person you wish to remove.
The URL should contain the ID of the Person you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Response status codes
@ -55,7 +55,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `person.id` | Number | The ID of the Person |
| `person.createdAt` | String | Date string indicating the moment the Person was created |
| `person.img` | String | The URL to the image stored with this Person |
@ -101,4 +101,3 @@ const clone = axios.post(
}
}
```

4
markdown/dev/reference/backend/api/people/create/en.md
View file

@ -2,7 +2,7 @@
title: Create a Person
---
Creates a new Person.
Creates a new Person.
## Access control
@ -50,7 +50,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `person.id` | Number | The ID of the Person |
| `person.createdAt` | String | Date string indicating the moment the Person was created |
| `person.img` | String | The URL to the image stored with this Person |

5
markdown/dev/reference/backend/api/people/delete/en.md
View file

@ -18,9 +18,9 @@ Deleting a Person is possible via these endpoints:
| <Method delete /> | `/people/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method delete /> | `/people/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Person you wish to remove.
The URL should contain the ID of the Person you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Response status codes
@ -56,4 +56,3 @@ await axios.delete(
These endpoints return status code <StatusCode status="204"/> (no content) on
success, with no response body.
</Note>

7
markdown/dev/reference/backend/api/people/en.md
View file

@ -11,7 +11,7 @@ for.
## Notes
### The `imperial` property is a boolean
### The `imperial` property is a Boolean
- If the `imperial` property is `false`, the person wants metric units.
- If the `imperial` property is `true`, the person wants imperial units.
@ -25,12 +25,12 @@ object](/reference/settings/measurements).
The backend will only accept known measurements listed in the configuration file.
<Comment by="joost">
##### Why we use measies instead of measurements
##### Why we use measies instead of measurements
First of all, _measies_ is a cute and adorable alternative for _measurements_
coined by Karen. She deserves all the credit.
But also, I am slightly dyslexic and for some reason, I often drop the middle
_e_ when typing measurments (sic).
_e_ when typing measurements' (sic).
Those typos lead to bugs and I find it much easier to write _measies_.
So because fewer bugs, plus did I mention it's cute?
@ -42,4 +42,3 @@ So because fewer bugs, plus did I mention it's cute?
The `settings` property should hold [a settings object](/reference/settings)
that can be passed to [the Pattern
constructor](/reference/api/pattern#creating-a-pattern).

4
markdown/dev/reference/backend/api/people/read/en.md
View file

@ -2,7 +2,7 @@
title: Read a Person
---
Reads an existing Person.
Reads an existing Person.
## Access control
@ -56,7 +56,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `person.id` | Number | The ID of the Person |
| `person.createdAt` | String | Date string indicating the moment the Person was created |
| `person.img` | String | The URL to the image stored with this Person |

6
markdown/dev/reference/backend/api/people/update/en.md
View file

@ -18,9 +18,9 @@ Updating an existing Person is possible via these endpoints:
| <Method put /> | `/people/:id/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
| <Method put /> | `/people/:id/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
## Request url
## Request URL
The url should contain the ID of the Person you wish to remove.
The URL should contain the ID of the Person you wish to remove.
It replaces the `:id` placeholder in the [endpoints listed above](#endpoints).
## Request body
@ -56,7 +56,7 @@ in the response body should indicate the nature of the problem.
| 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 occured. |
| `error` | String | Will give info on the nature of the error. Only set if an error occurred. |
| `person.id` | Number | The ID of the Person |
| `person.createdAt` | String | Date string indicating the moment the Person was created |
| `person.img` | String | The URL to the image stored with this Person |

4
markdown/dev/reference/backend/api/rbac/en.md
View file

@ -18,14 +18,14 @@ The available roles and their privilege levels are:
We offer more fine-grained control over the permission level when
authenticating with API keys. When you create an API key, you can choose any
permissing level that is equal or lower than your own role's permission level.
permissioning level that is equal or lower than your own role's permission level.
This allows you to -- for example -- generate an API key that only have read
access to your data.
## Permission levels
The table below lists the priviledge of all levels as well as their
The table below lists the privilege 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> |