twochi_bot

Introduction

The function of the API is basically to access the images' metadata stored in the database.

ENV

• PORT: Specify the port the webserver will run on. Default(8000)
• DB_TABLE: Specify the table images are stored on. Default("images")
• DB_PASS: Specify the password of the database. Default("")
• DB_URI: Specify url or file of the database. Default("sqlite.db")
  • Start with "postgresql://" to use the postgres engine
  • The postgres url must contain the User, Host, Port and Database Example: "postgresql://root@postgres:5432/bot"
  • You can specify ":memory:" for in memory DB, this will make the application not work as expected.
• TOKEN_SECRET: Base64 encoded key to generate the tokens for the client to verify the image was previously verified by the backend.
• INSTANCE_BIO: Bio of the bot, explaining what it does, bio in the instance will be overwriten by this plus remaining images.
• OUT_OF_IMAGES_MESSAGE: Message to alert the maintainers of the bot about running out of images
• INSTANCE_TOKEN: Token needed to post on the fedi instance, you can get it from an admin panel, dev tools or the /bot/register endpoint
• INSTANCE_URL: URL of the fedi instance the pot will post to.
• BOT_MAINTAINERS: String containing the username of the maintainers, separated by spaces. It must be the complete username, ie: @sleepinggaysbot@social.siesta.cat

Usage

The API exposes some endpoints to interact with the database.

GET /images

Allows to get a list of image documents.

Query params

• limit: an optional parameter, which accepts a non-negative integer that dictates the number of documents that the list will have. If its value is equal to 0, or if this parameter is missing, the endpoint will return all the image documents in the database.
• status: an optional parameter, which accepts the values consumed, available and unavailable. It filters the documents that have only the status attribute equal to that indicated in the parameter's value. If the parameter is missing, no filter will be applied to the document.

Example

• GET /images?limit=5&status=available will return 5 documents that have the available value in their status attribute.

GET /images/<id>

Allows to get an image document.

Params

• id: the id of the document to be modified.

Example

GET /images/61f7e48f0c651345677b7775 will get the document referenced by the id param.

PUT /images/<id>

Modifies an existing image document. The request must provide a JSON-formatted body, with one or more valid document attributes. The existing document attributes will be replaced with the provided new ones.

Params

• id: the id of the document to be modified.

Example

• PUT /images/61f7e48f0c651345677b7775 with body { "status": "consumed" } will modify the document referenced by the id param, changing their status value to consumed.

POST /images

Allows to insert a new image document.

Example

POST /images with body { "url": "https://my-images.com/foo.jpg", "status": "available"} will insert the image passed on the request body into the database.

GET /verify/image

Allows to get an image verification document, it will contain a url and a cryptographic signature of the image.

Example

GET /verify/image will get the followong document:

{
  "url":"https://example.com/82128e09a7eea4fbf0be9c7b5.png",
  "token":"5SI4I9RR8rxFAPH9ClPsPnwyYZsrHj9tS9vLuckPuZIkfQyEd/4PaqVHidKDCO4pf49HvPPWiYO4nxN1V99mtg=="
}

POST /verify/image/review

Allows to insert a review document to discard or approve an image.

Example

POST /verify/image/review with the following body will change the status of the image sent from "unverified" to, in this case "verified":

{
  "url":"https://example.com/82128e09a7eea4fbf0be9c7b5.png",
  "token":"5SI4I9RR8rxFAPH9ClPsPnwyYZsrHj9tS9vLuckPuZIkfQyEd/4PaqVHidKDCO4pf49HvPPWiYO4nxN1V99mtg==",
  "is_accepted": true
}

POST /bot/post/image

Sending a request to this endpoint will trigger the workflow to post an image from the available images into the instance specified on the env vars.

POST /bot/post/debug

Sending a request to this endpoint will post the sent status with the sent visibility into the instance specified on the env vars. Visibility must be one of the following:

• "direct"
• "private"
• "public"
• "unlisted"

Example

This body will send the "This is a Test!" text in the status with the visibility of unlisted.

{
  "status": "This is a Test!",
  "visibility": "unlisted"
}

Running the tests

make test

Running locally

make run

To post images at a constant rate, we recommend using the folowing curl:

curl http://localhost:8000/bot/post/image -X POST