API

API

wanderer comes with a fully functional RESTful API out of the box. It largely follows the CRUD conventions implemented by the PocketBase backend. All endpoints are available at http://<wanderer_host>/api/v1. The full technical API documentation can be found at http://<wanderer_host>/docs/api/index.html and is also provided in this wiki.

Authentication

wanderer's API uses cookie-based authentication. To receive an auth cookie send a request to the /auth/login endpoint. The request must contain a JSON body in the following form:

{
    username: string,
    password: string
}

The cookie from the response can be sent in a subsequent request to authenticate it.

Example

curl --header "Content-Type: application/json" --request POST \
--cookie-jar ./wanderer-credentials \
--data '{"username":"MyUser","password":"mysecretpassword"}' \
http://localhost:3000/api/v1/auth/login

Upload trails

One common use case for wanderer's API is bulk uploading GPX files to create new trails. For that, the API provides a separate endpoint: /trail/upload. You must first log in to use the endpoint. Afterwards you can send a GPX file to the endpoint to let wanderer parse it an create a new trail in your collection. wanderer will try to infer as much information as possible from the file itself. All additional information can be added to the trail via the UPDATE endpoint.

Example

curl --location --request PUT 'http://localhost:3000/api/v1/trail/upload' \
--header 'Content-Type: application/gpx+xml' \
--cookie './wanderer-credentials' \
--data-binary '@my_trail.gpx'

Auto-upload folder

wanderer also supports bulk uploading of trails via an auto-upload folder. A cronjob fetches all files from this folder and uploads them automatically every 15 minutes. This feature is currently only available for docker installations. If you want to replicate it in a bare metal installation you will need to create your own cronjob using the web/cron.sh script.

⚠️ Successfully uploaded files will be deleted from the auto-upload folder.

ℹ️ Currently only GPX files are supported

Configuration

The following environment variables must be present in the wanderer-web docker container and set to valid values.

Environment Variable	Description	Default
UPLOAD_FOLDER	Path to the auto-upload folder	/app/uploads
UPLOAD_USER	Username of the account that will be the author of the uploaded trails
UPLOAD_PASSWORD	Password of the account that will be the author of the uploaded trails

Volume

Make sure to mount the upload folder as a volume to your host system. The default docker-compose.yml already includes this volume. Ensure that the mapped value matches the one in the UPLOAD_FOLDER environment variable.

Manually run the upload job

In case you do not want to wait until the next scheduled execution you can also run the job manually:

docker exec -it wanderer-web run-parts /etc/periodic/15min