feat(markdown): Work on backend docs
This commit is contained in:
joostdecock
parent
6c2cb71f51
commit
4edfe29726
17 changed files with 1196 additions and 347 deletions
110
markdown/dev/reference/backend/api/patterns/clone/en.md
Normal file
110
markdown/dev/reference/backend/api/patterns/clone/en.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
title: Clone a Pattern
|
||||
---
|
||||
|
||||
Create a new Pattern by cloning an existing one.
|
||||
|
||||
## Access control
|
||||
|
||||
The [Permission level](/reference/backend/api/rbac) required to clone a
|
||||
Pattern depends on:
|
||||
|
||||
- Whether the Pattern is `public`
|
||||
- Who created the Pattern
|
||||
|
||||
The details are outlined in the table below:
|
||||
|
||||
| | Public Patterns | Non-Public Patterns |
|
||||
| ---------------: | :-------------: | :-----------------: |
|
||||
| **Your own** | `0` or higher | `4` or higher |
|
||||
| **Other user's** | `0` or higher | `5` or higher |
|
||||
|
||||
## Endpoints
|
||||
|
||||
Creating a new API key is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <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
|
||||
|
||||
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
|
||||
|
||||
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 | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `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 |
|
||||
| `pattern.design` | String | The name of the design of which this Pattern is an instance |
|
||||
| `pattern.img` | String | The URL to the image stored with this Pattern |
|
||||
| `pattern.name` | String | The name of the Pattern |
|
||||
| `pattern.notes` | String | The notes stored with the Pattern |
|
||||
| `pattern.personId` | Number | The ID of the Person for whom the Pattern was created |
|
||||
| `pattern.public` | Boolean| Indicates whether the Pattern is publicly accessible or not |
|
||||
| `pattern.settings` | Object | The settings used to (re-)create the Pattern |
|
||||
| `pattern.userId` | Number | The ID of the user who created the Pattern |
|
||||
| `pattern.updatedAt` | String | Date string indicating the last time the pattern was updated |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const apiKey = axios.post(
|
||||
'https://backend.freesewing.org/patterns/10/clone/jwt',
|
||||
null,
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"pattern": {
|
||||
"id": 19,
|
||||
"createdAt": "2022-11-19T16:29:33.346Z",
|
||||
"data": {
|
||||
"some": "value"
|
||||
},
|
||||
"design": "aaron",
|
||||
"img": "https://cdn.sanity.io/images/hl5bw8cj/production/a1565c8c6c70cfe7ea0fdf5c65501cd885adbe78-200x187.png",
|
||||
"name": "Just a test",
|
||||
"notes": "These are my notes",
|
||||
"personId": 17,
|
||||
"public": true,
|
||||
"settings": {
|
||||
"sa": 5
|
||||
},
|
||||
"userId": 10,
|
||||
"updatedAt": "2022-11-19T16:29:33.346Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
121
markdown/dev/reference/backend/api/patterns/create/en.md
Normal file
121
markdown/dev/reference/backend/api/patterns/create/en.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
title: Create a Pattern
|
||||
---
|
||||
|
||||
Creates a new Pattern. This is typically used when users choose to save a pattern.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/api/rbac) `4` or higher is required to create a Pattern
|
||||
|
||||
## Endpoints
|
||||
|
||||
Creating a new Pattern is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method post /> | `/patterns/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
|
||||
| <Method post /> | `/patterns/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
|
||||
|
||||
## Request body
|
||||
The request body is a JSON object with the following properties:
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `data` | `object` | Any additional data to store with the pattern |
|
||||
| `design` | `string` | The name of the design this Pattern is an instance of |
|
||||
| `img` | `object` | An image [data-uri][duri] to store with this Pattern |
|
||||
| `name` | `string` | A name for the Pattern |
|
||||
| `notes` | `string` | User notes for the pattern |
|
||||
| `person` | `object` | The ID of the person to associate with this pattern |
|
||||
| `settings` | `object` | The settings object to (re-)create the Pattern |
|
||||
|
||||
## 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 | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `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 |
|
||||
| `pattern.design` | String | The name of the design of which this Pattern is an instance |
|
||||
| `pattern.img` | String | The URL to the image stored with this Pattern |
|
||||
| `pattern.name` | String | The name of the Pattern |
|
||||
| `pattern.notes` | String | The notes stored with the Pattern |
|
||||
| `pattern.personId` | Number | The ID of the Person for whom the Pattern was created |
|
||||
| `pattern.public` | Boolean| Indicates whether the Pattern is publicly accessible or not |
|
||||
| `pattern.settings` | Object | The settings used to (re-)create the Pattern |
|
||||
| `pattern.userId` | Number | The ID of the user who created the Pattern |
|
||||
| `pattern.updatedAt` | String | Date string indicating the last time the pattern was updated |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const pattern = await axios.post(
|
||||
'https://backend.freesewing.org/patterns/jwt',
|
||||
{
|
||||
data: {
|
||||
some: 'value',
|
||||
}
|
||||
design: "aaron",
|
||||
img: "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...truncated",
|
||||
name: "Just a test",
|
||||
notes: "These are my notes",
|
||||
person: 17,
|
||||
public: true,
|
||||
settings: {
|
||||
sa: 5,
|
||||
},
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"pattern": {
|
||||
"id": 10,
|
||||
"createdAt": "2022-11-19T16:29:33.346Z",
|
||||
"data": {
|
||||
"some": "value"
|
||||
},
|
||||
"design": "aaron",
|
||||
"img": "https://cdn.sanity.io/images/hl5bw8cj/production/a1565c8c6c70cfe7ea0fdf5c65501cd885adbe78-200x187.png",
|
||||
"name": "Just a test",
|
||||
"notes": "These are my notes",
|
||||
"personId": 17,
|
||||
"public": true,
|
||||
"settings": {
|
||||
"sa": 5
|
||||
},
|
||||
"userId": 10,
|
||||
"updatedAt": "2022-11-19T16:29:35.023Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[duri]: https://en.wikipedia.org/wiki/Data_URI_scheme
|
||||
59
markdown/dev/reference/backend/api/patterns/delete/en.md
Normal file
59
markdown/dev/reference/backend/api/patterns/delete/en.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
title: Delete a Pattern
|
||||
---
|
||||
|
||||
Deletes an existing Pattern.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/api/rbac) `4` or higher is required to delete a Pattern
|
||||
- [Permission level](/reference/backend/api/rbac) `8` is required to delete **another user's** Pattern
|
||||
|
||||
## Endpoints
|
||||
|
||||
Deleting a Pattern is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <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
|
||||
|
||||
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
|
||||
|
||||
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/patterns/10/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>
|
||||
|
||||
34
markdown/dev/reference/backend/api/patterns/en.md
Normal file
34
markdown/dev/reference/backend/api/patterns/en.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: Patterns
|
||||
---
|
||||
|
||||
Patterns hold information on and settings for a user's patterns.
|
||||
|
||||
## Endpoints
|
||||
|
||||
<ReadMore />
|
||||
|
||||
## Notes
|
||||
|
||||
### The `design` property should hold the design
|
||||
|
||||
The `design` property should hold the name of the FreeSewing design.
|
||||
For example, `aaron`.
|
||||
|
||||
### The `notes` vs `data` properties
|
||||
|
||||
Both the `data` and `notes` properties can hold additional information about
|
||||
the pattern.
|
||||
|
||||
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`.
|
||||
|
||||
### 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).
|
||||
|
||||
109
markdown/dev/reference/backend/api/patterns/read/en.md
Normal file
109
markdown/dev/reference/backend/api/patterns/read/en.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
title: Read a Pattern
|
||||
---
|
||||
|
||||
Reads an existing Pattern.
|
||||
|
||||
## Access control
|
||||
|
||||
The [Permission level](/reference/backend/api/rbac) required to read a
|
||||
Pattern depends on:
|
||||
|
||||
- Whether the Pattern is `public`
|
||||
- Who created the Pattern
|
||||
|
||||
The details are outlined in the table below:
|
||||
|
||||
| | Public Patterns | Non-Public Patterns |
|
||||
| ---------------: | :-------------: | :-----------------: |
|
||||
| **Your own** | `0` or higher | `4` or higher |
|
||||
| **Other user's** | `0` or higher | `5` or higher |
|
||||
|
||||
## Endpoints
|
||||
|
||||
Reading a Pattern is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <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
|
||||
|
||||
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
|
||||
|
||||
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 | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `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 |
|
||||
| `pattern.design` | String | The name of the design of which this Pattern is an instance |
|
||||
| `pattern.img` | String | The URL to the image stored with this Pattern |
|
||||
| `pattern.name` | String | The name of the Pattern |
|
||||
| `pattern.notes` | String | The notes stored with the Pattern |
|
||||
| `pattern.personId` | Number | The ID of the Person for whom the Pattern was created |
|
||||
| `pattern.public` | Boolean| Indicates whether the Pattern is publicly accessible or not |
|
||||
| `pattern.settings` | Object | The settings used to (re-)create the Pattern |
|
||||
| `pattern.userId` | Number | The ID of the user who created the Pattern |
|
||||
| `pattern.updatedAt` | String | Date string indicating the last time the pattern was updated |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const pattern = await axios.get(
|
||||
'https://backend.freesewing.org/patterns/10/jwt',
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"pattern": {
|
||||
"id": 10,
|
||||
"createdAt": "2022-11-19T16:29:33.346Z",
|
||||
"data": {
|
||||
"some": "value"
|
||||
},
|
||||
"design": "aaron",
|
||||
"img": "https://cdn.sanity.io/images/hl5bw8cj/production/a1565c8c6c70cfe7ea0fdf5c65501cd885adbe78-200x187.png",
|
||||
"name": "Just a test",
|
||||
"notes": "These are my notes",
|
||||
"personId": 17,
|
||||
"public": true,
|
||||
"settings": {
|
||||
"sa": 5
|
||||
},
|
||||
"userId": 10,
|
||||
"updatedAt": "2022-11-19T16:29:35.023Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
119
markdown/dev/reference/backend/api/patterns/update/en.md
Normal file
119
markdown/dev/reference/backend/api/patterns/update/en.md
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
---
|
||||
title: Update a Pattern
|
||||
---
|
||||
|
||||
Updates an existing Pattern.
|
||||
This is typically used when users choose to save/overwrite a pattern.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/api/rbac) `4` or higher is required to update a Pattern
|
||||
- [Permission level](/reference/backend/api/rbac) `8` is required to update **another user's** Pattern
|
||||
|
||||
## Endpoints
|
||||
|
||||
Updating an existing Pattern is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <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
|
||||
|
||||
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
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `data` | `object` | Any additional data to store with the pattern |
|
||||
| `design` | `string` | The name of the design this Pattern is an instance of |
|
||||
| `img` | `object` | An image [data-uri][duri] to store with this Pattern |
|
||||
| `name` | `string` | A name for the Pattern |
|
||||
| `notes` | `string` | User notes for the pattern |
|
||||
| `person` | `object` | The ID of the person to associate with this pattern |
|
||||
| `settings` | `object` | The settings object to (re-)create the Pattern |
|
||||
|
||||
## 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 | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `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 |
|
||||
| `pattern.design` | String | The name of the design of which this Pattern is an instance |
|
||||
| `pattern.img` | String | The URL to the image stored with this Pattern |
|
||||
| `pattern.name` | String | The name of the Pattern |
|
||||
| `pattern.notes` | String | The notes stored with the Pattern |
|
||||
| `pattern.personId` | Number | The ID of the Person for whom the Pattern was created |
|
||||
| `pattern.public` | Boolean| Indicates whether the Pattern is publicly accessible or not |
|
||||
| `pattern.settings` | Object | The settings used to (re-)create the Pattern |
|
||||
| `pattern.userId` | Number | The ID of the user who created the Pattern |
|
||||
| `pattern.updatedAt` | String | Date string indicating the last time the pattern was updated |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const udpate = await axios.put(
|
||||
'https://backend.freesewing.org/patterns/10/jwt',
|
||||
{
|
||||
data: {
|
||||
some: 'new value',
|
||||
}
|
||||
public: false,
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"pattern": {
|
||||
"id": 10,
|
||||
"createdAt": "2022-11-19T16:29:33.346Z",
|
||||
"data": {
|
||||
"some": "new value"
|
||||
},
|
||||
"design": "aaron",
|
||||
"img": "https://cdn.sanity.io/images/hl5bw8cj/production/a1565c8c6c70cfe7ea0fdf5c65501cd885adbe78-200x187.png",
|
||||
"name": "Just a test",
|
||||
"notes": "These are my notes",
|
||||
"personId": 17,
|
||||
"public": false,
|
||||
"settings": {
|
||||
"sa": 5
|
||||
},
|
||||
"userId": 10,
|
||||
"updatedAt": "2022-11-19T16:43:39.223Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[duri]: https://en.wikipedia.org/wiki/Data_URI_scheme
|
||||
Loading…
Add table
Add a link
Reference in a new issue