Guide: Setting up the API server¶
In this guide, we will show you how to setup the API server and how to use it.
Quickstart¶
To start this image you first need to have a Postgress database running. The expose port of the API is 8000
.
Automatically¶
A full `docker-compose.yml
<https://github.com/IceKhan13/purplecaffeine/blob/main/docker-compose.yml>`__ is provided. It’s containing postgres and the api.
Manually¶
Then you need to set some variables :
export SERV_KEY=test
export DEBUG=0 # Optional, default: 0
export ALLOWED_HOSTS="localhost" # Optional, default: "*"
export DB_NAME=postgres # Optional, default: "purplecaffeine"
export DB_USER=root # Optional, default: "purplecaffeine"
export DB_PASSWORD=root # Optional, default: "purplecaffeinepassword"
export DB_HOST=postgres # Optional, default: "localhost"
export DB_PORT=5432 # Optional, default: "5432"
export DB_SCHEMA=public # Optional, default: "public"
export DJANGO_SUPERUSER_USERNAME=admin
export DJANGO_SUPERUSER_PASSWORD=admin
export DJANGO_SUPERUSER_EMAIL=admin@admin.admin
You can run the image like so :
docker run --name purplecaffeine \
-p 8000:8000 \
-e SERV_KEY="${SERV_KEY}" -e DEBUG="${DEBUG}" \
-e ALLOWED_HOSTS="${ALLOWED_HOSTS}" \
-e DB_NAME="${DB_NAME}" -e DB_HOST="${DB_HOST}" -e DB_PORT="${DB_PORT}" \
-e DB_USER="${DB_USER}" -e DB_PASSWORD="${DB_PASSWORD}" \
-e DB_SCHEMA="${DB_SCHEMA}" \
-e DJANGO_SUPERUSER_USERNAME="${DJANGO_SUPERUSER_USERNAME}" \
-e DJANGO_SUPERUSER_PASSWORD="${DJANGO_SUPERUSER_PASSWORD}" \
-e DJANGO_SUPERUSER_EMAIL="${DJANGO_SUPERUSER_EMAIL}" \
purplecaffeine:latest
Or using a docker-compose.yml
file :
services:
purplecaffeine:
container_name: purplecaffeine
image: purplecaffeine
environment:
SERV_KEY: ${SERV_KEY:-test}
DEBUG: ${DEBUG:-0}
DB_NAME: ${DB_NAME:-purplecaffeine}
DB_USER: ${DB_USER:-purplecaffeine}
DB_PASSWORD: ${DB_PASSWORD:-purplecaffeinepassword}
DB_HOST: ${DB_HOST:-"postgres"}
DB_PORT: ${DB_PORT:-5432}
DB_SCHEMA: ${DB_SCHEMA:-public}
DJANGO_SUPERUSER_USERNAME: ${DJANGO_SUPERUSER_USERNAME:-admin}
DJANGO_SUPERUSER_PASSWORD: ${DJANGO_SUPERUSER_PASSWORD:-admin}
DJANGO_SUPERUSER_EMAIL: ${DJANGO_SUPERUSER_EMAIL:-"adm@adm.adm"}
ports:
- 8000:8000
Documentation¶
Get a token¶
curl -X POST "http://localhost:8000/api/token/" \
-H "Content-Type: application/json" \
--data-raw '{
"username": "admin",
"password": "admin"
}'
Response:
{
"refresh": "...",
"access": "..."
}
Get experiment¶
curl -X GET "http://localhost:8000/api/trials/1/" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json"
Response:
{
"id":1,
"uuid":"...",
"name":"...",
"description":"...",
"...": "..."
}
Get all experiments¶
curl -X GET "http://localhost:8000/api/trials/" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json"
Response:
{
"count":1,
"next":null,
"previous":null,
"results":[{"id":1,"uuid":"...","name":"...", "...":"..."}]
}
Search and pagination
curl -X GET "http://localhost:8000/api/trials/?query=term&offset=0&limit=20" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json"
Response:
{
"count":1,
"next":null,
"previous":null,
"results":[{"id":1,"uuid":"...","name":"...", "...":"..."}]
}
Post experiment¶
curl -X POST "http://localhost:8000/api/trials/" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" -H "accept: application/json" \
--data-raw '{
"name": "My super experiment",
"description": "My super experiments desciption",
"storage": {"__type__": "PurpleCaffeineBackend"},
"metrics": [["nb_qubits", 2]],
"parameters": [["OS", "ubuntu"]],
"circuits": [],
"operators": [],
"artifacts": [],
"texts": [],
"arrays": [],
"tags": []
}'
Update experiment¶
curl -X PUT "http://localhost:8000/api/trials/1/" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" -H "accept: application/json" \
--data-raw '{
"name": "My super experiment",
"description": "My super experiments desciption",
"storage": {"__type__": "PurpleCaffeineBackend"},
"metrics": [["nb_qubits", 2]],
"parameters": [["OS", "ubuntu"]],
"circuits": [],
"operators": [],
"artifacts": [],
"texts": [],
"arrays": [],
"tags": []
}'
Delete experiment¶
curl -X DELETE "http://localhost:8000/api/trials/1/"