Party-API

This is a REST API backend specifically designed to streamline the visitor registration process for demoparties. To maintain simplicity, all data is persisted in an SQLite database.

Running

The following environment variables are used for configuration:

Variable	Description	Default value
API_KEY	Key protecting the /admin endpoints
CORS_ORIGIN	CORS preflight URL restriction	*
SQLITE_DB	Path to SQLite database file	data.db
LISTEN_ADDR	IP and port to listen on	127.0.0.1:3000
CAP_INSTANCE_URI	Cap site endpoint
CAP_SECRET	Cap site secret

Sample Docker Compose

Create a docker-compose.yml file with the following content, replacing myapikey with your own key.

services:
  party-api:
    image: ghcr.io/memoryleek/party-api:latest
    ports:
      - 3000:3000
    volumes:
      - ./party-api-data:/data
    environment:
      - API_KEY=myapikey
      - SQLITE_DB=/data/party-api.db

Then run docker-compose up -d to start it. The SQLite database will be stored outside the container as party-api-data/party-api.db.

Example requests

Fetching registered visitors

curl -i -H 'Accept: application/json' http://localhost:3000/visitors

HTTP/1.1 200 OK
content-type: application/json
content-length: 73
date: Sat, 10 Jun 2023 19:16:20 GMT

[
  {
    "id": 1,
    "nick": "Lorem",
    "group": null
  },
  {
    "id": 2,
    "nick": "Ipsum Dolor",
    "group": "Sit Amet"
  }
]

Registering as a visitor

Due to problems with bots making spam registrations the /register endpoint can be configured to require a proof-of-work to be provided by the client using the self-hostable CAPTCHA tool Cap. This is only enabled/required if both CAP_INSTANCE_URI and CAP_SECRET are set.

Note that the fields email and extra are not shown in the public GET /visitors listing, but are intended only for the party organizers.

curl -i -H 'Content-Type: application/json' \
     -X POST \
     -d '{"nick":"Lorem","group":"Ipsum","email":"lorem@example.com","extra":"Allergic to metaballs"}' \
     http://localhost:3000/register

HTTP/1.1 201 Created
content-length: 0
date: Sat, 10 Jun 2023 19:17:23 GMT

With proof-of-work

See the Cap Quickstart for detailed information about how to add the Cap widget to your frontend.

The CAP_INSTANCE_URI should point to the actual verification endpoint, like https://<your-instance>/<site-key>/siteverify. CAP_SECRET is your generated secret key, like sk-xxx.

curl -i -H 'Content-Type: application/json' \
     -X POST \
     -d '{"nick":"Lorem","group":"Ipsum","email":"lorem@example.com","extra":"Allergic to metaballs","cap-token":"fb69400c43:1ab132ceaeb7be79:d33ea92570f08527ba917c8ba24cc3"}' \
     http://localhost:3000/register

HTTP/1.1 201 Created
content-length: 0
date: Sat, 10 Jun 2023 19:17:23 GMT

Fetching full visitor data

This is only available for organizers, authorized by API_KEY.

curl -i -H 'Accept: application/json' \
     -H 'Authorization: Bearer myapikey' \
     http://localhost:3000/admin/visitors

HTTP/1.1 200 OK
content-type: application/json
content-length: 277
date: Tue, 04 Jul 2023 18:28:11 GMT

[
  {
    "id":1,
    "created_at":"2023-07-04T18:26:51.724571400Z",
    "ip":"127.0.0.1:49580",
    "nick":"Lorem",
    "group":null,
    "email":null,
    "extra":null
  },
  {
    "id":2,
    "created_at":"2023-07-04T18:26:56.288133200Z",
    "ip":"127.0.0.1:49582",
    "nick":"Ipsum Dolor",
    "group":"Sit Amet",
    "email":null,
    "extra":null
  }
]

Deleting a visitor

This is only available for organizers, authorized by API_KEY.

curl -i -H 'Accept: application/json' \
     -H 'Authorization: Bearer myapikey' \
     -X DELETE \
     http://localhost:3000/admin/visitors/1

HTTP/1.1 204 No Content
content-length: 0
date: Tue, 04 Jul 2023 18:30:56 GMT