API Basics
Not recommended for production usage!
The API is currently not meant for public usage. There are no API keys available and endpoints might change unexpectedly with the release of a new version.
If you want to interact with your WebCrate instance programmatically or want to integrate it with other tools, use the API!
Overview
WebCrate's API consists of different REST endpoints you can call. It is available under the /api
path of your WebCrate instance.
The API is split into different groups:
- links - can be accessed under
/api/link
- crates - can be accessed under
/api/crate
- config - can be accessed under
/api/config
- public - can be accessed under
/api/public
- search - can be accessed under
/api/search
Authentication
Currently the only way to access protected endpoints is by being logged into Deta Space in the same browser. We are working together with the Deta Space team on adding API keys/tokens for easier access.
Requests
WebCrate's API supports the following http request methods:
GET
Use the GET
method to retrieve a single or multiple items:
GET /api/link
To get a specific item like a link or crate, specify it's id in the request path:
GET /api/link/:id
POST
Use the POST
method to add/create an item like a link or crate:
POST /api/link
You have to specify the data you want to add as the request body in the JSON format.
PUT
Use the PUT
method to modify/update a specific item like a link or crate:
PUT /api/link/:id
You have to specify the data you want to modify/update as the request body in the JSON format.
DELETE
Use the DELETE
method to delete/remove an speicifc item like a link or crate:
DELETE /api/link/:id
Responses
The API will only return JSON data in the following format:
{
"status": 200,
"message": "ok",
"data": {}
}
Successfull requests will always return a http status code of 200
as well as the have the status in the response set to 200
and the message set to ok
. The data key contains the requested data/the response data. The format depends on the request, it is either an object or an array.
If the request is paginated there will also be the last
present containing the id
of the last item. More info in the pagination section.
Errors
If the server encounters an error during the processing of your request it will return a JSON response in the following format:
{
"status": 400,
"message": "bad request",
"error": {
"message": "Cannot read property 'key' of null" // Optionally more information about the error
}
}
Unsuccessfull requests will always return the status code as the http status code and as the status in the response. The message is always present and contains a description of the status code. Sometimes there is also a error
object set which contains a more detailed version of the error.
Status codes
Here are all the available status codes and their meanings:
Code | Message | Meaning |
---|---|---|
200 | ok | Request completed successfully |
400 | bad request | The data you provided was malformed or invalid |
401 | unauthorized | You are not authenticated |
403 | forbidden | You are not allowed to access that route |
404 | not found | The resource you are trying to access doesn't exist |
409 | conflict | There already exists something that's conflicting with the provided data |
429 | too many requests | You are sending too many requests in a short time frame |
500 | server error | An internal server error occurred. If this keeps happening open a GitHub issue |
Pagination
For most resources the data
key will contain a single object. For some requests you may be getting an array of objects back.
By default the API will only return a maximum of 20 items at once. This limit can be controlled with the limit
URL parameter. If you set it to 0
, it will return everything, for any other integer the number of items will be limited to it.
If there are more items available then the limit allows, the last
key of the reponse will be set to the id of the last item returned.
Here's an example:
GET /api/link?limit=10
Will return:
{
"status": 200,
"message": "ok",
"last": "demoId",
"data": [ {...}, {...}, ...] // 10 items
}
To get the next 10 items:
GET /api/link?limit=10&last=demoId