Automating tedious tasks with our API

Sometime automation is desired for a specific task. For instance uploading a visualization directly from a script. To help with this we expose some endpoints that can be used to automate tasks. This small guide requires some basic knowledge of curl and json.

Using the python package

We have created a small package to interact with the API. The package is still in development and may change but it should provide a good starting point for automating tasks. You may find more information on its usage here.

pip install snip-python

Using the Endpoints directly

Generally any API endpoint can be used using your accounts or using an token. Each token is limited to a single book and allow you to interact with the book without the need to login. This is primarily useful for automation tasks.

You may create a token for any book you are the owner of. To create a token you have to navigate to the book settings page and click on the Access tab. There you will find further instructions on how to create a token.

Home>Edit book>Access>Api token

Uploading and creating snippets

Snip is using a number of different snippets to display data. We allow you to create and upload snippets to your labbook. The snippets are then placed on the books queue and can be placed on any page in the book.

Schemas

Snippets are made from a number of schemas that define the structure of the snippets. The schemas are used to validate the snip data and to provide a consistent interface for the snippets. To use our api your uploaded snippets have to follow the schemas.

They allow you to find out what kind of data is expected from our backend and how to structure it. You may find all available schemas on the schemas page.

Testing snippets

To test if a snippet is valid you may use the advanced upload page. There you may insert any json object and test if it is valid. This is useful to check if your json object is correctly formatted and to get some visual feedback on how the snippet will look like.

Alternatively you may use the ?test=true parameter in the api endpoint to test if a snippet is valid. This will not upload the snippet but will return a json object indicating if the snippet is valid or not. Yet another way if you want a preview of the snippet you may use the /render/snip endpoint which returns a rendered snippet as image.

Uploading via the endpoint

The api endpoint for uploading snippets is:

https://snip.roentgen.physik.uni-goettingen.de/api/books/<book_id>/upload

You may upload any snippet in json format via a POST request to the endpoint. The snippet will be validated and if it is valid it will be uploaded to the book. You may also test the snippet by adding the ?test=true parameter to the url. This will not upload the snippet but will return a json object indicating if the snippet is valid or not.

Examples

Images

Images may be uploaded directly as an snippet of image type or alternatively as a file.

//image.json
{
    "type": "image",
    "book_id": 1,
    "data": {
        "blob" :{
            "mime": "image/png",
            "data": "base64_encoded_image"
        }
    }
}

This can than be uploaded using the following curl request:

curl https://snip.roentgen.physik.uni-goettingen.de/api/books/[BOOK_ID]/upload?test=true \
    -X POST \
    -H "Authorization: Bearer [YOUR_TOKEN_HERE]" \
    -H "Content-Type: application/json" \
    -d "@./image.json"

Alternatively and arguable easier for a simple image upload you may use the following curl request to upload a file directly:

curl https://snip.roentgen.physik.uni-goettingen.de/api/books/[BOOK_ID]/upload?test=true \
    -X POST \
    -H "Authorization: Bearer [YOUR_TOKEN_HERE]" \
    -F "file=@./figure.png"

Text

You may use the following json object to upload a text snippet:

//text.json
{
    "type": "text",
    "book_id": 123,
    "data": {
        "text": "Hello, World!"
    },
    "view": {
        "__comment": "View is optional and may be changed!",
        "size": 20,
        "x": 100,
        "y": 200,
        "rot": 42
    }
}

curl https://snip.roentgen.physik.uni-goettingen.de/api/books/[BOOK_ID]/upload?test=true \
    -X POST \
    -H "Authorization: Bearer [YOUR_TOKEN_HERE]" \
    -H "Content-Type: application/json" \
    -d "@./text.json"