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.

The easiest way to upload a snippet directly is to user the python package. You may find the documentation for the package on the snip-python documentation page.

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"