feat: initial commit

src/API.md

@@ -0,0 +1,70 @@
+:::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