71 lines
1.9 KiB
Markdown
71 lines
1.9 KiB
Markdown
|
:::warning[Under construction]
|
||
|
|
This documentation is a work in progress. Please [get in touch](/contact) with us if you have any questions.
|
||
|
|
:::
|
||
|
|
|
||
|
|
Learn how to use the jasima.app API.
|
||
|
|
Everything that can be done within the portal can also be achieved using our API, documented in this section.
|
||
|
|
|
||
|
|
## Authentication
|
||
|
|
|
||
|
|
We use an API key for authentication.
|
||
|
|
This should be passed to the API in an `Authorization` header:
|
||
|
|
|
||
|
|
```http request
|
||
|
|
Authorization: Bearer <token>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Data Format
|
||
|
|
|
||
|
|
The API uses JSON as the default format for both requests and responses, ensuring consistency and simplicity in data
|
||
|
|
handling:
|
||
|
|
|
||
|
|
* For GET requests, the API expects parameters to be passed via query strings.
|
||
|
|
* For other HTTP methods (e.g., POST, PUT), the request body (if required) should be formatted as JSON.
|
||
|
|
|
||
|
|
There is no need to explicitly specify content encoding in the headers, as the API assumes JSON by default for all
|
||
|
|
applicable requests and responses.
|
||
|
|
|
||
|
|
## Pagination
|
||
|
|
|
||
|
|
The API supports pagination to manage large datasets efficiently. Use the page and perPage query parameters to control the data returned in your requests.
|
||
|
|
Parameters:
|
||
|
|
|
||
|
|
* `page`: The page number to retrieve.
|
||
|
|
* `size`: The number of items to include per page.
|
||
|
|
|
||
|
|
Example request:
|
||
|
|
|
||
|
|
```http request
|
||
|
|
GET https://api.jasima.app/api/v1/widgets?page=1&size=10
|
||
|
|
```
|
||
|
|
|
||
|
|
Example response:
|
||
|
|
|
||
|
|
```http request
|
||
|
|
{
|
||
|
|
"items": [
|
||
|
|
],
|
||
|
|
"total": 0,
|
||
|
|
"page": 1,
|
||
|
|
"size": 10,
|
||
|
|
"pages": 0
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Bear in mind the following:
|
||
|
|
|
||
|
|
* The `page` field in the response indicates the current page being viewed.
|
||
|
|
* The `total` field shows the total number of items available.
|
||
|
|
* The `pages` field indicates the total number of pages, and can be used to determine whether there are additional pages
|
||
|
|
to fetch.
|
||
|
|
|
||
|
|
Use this structure to efficiently navigate through large datasets while ensuring optimal performance.
|
||
|
|
|
||
|
|
## Errors
|
||
|
|
|
||
|
|
:::info[TODO]
|
||
|
|
Document the common status codes, and the validation error response format.
|
||
|
|
:::
|
||
|
|
|
||
|
|
## Schemas
|