API Basics

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:

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