API REST

La API REST di OpenProject è un’interfaccia completa e documentata, basata sul formato HAL+JSON. Permette di automatizzare qualsiasi operazione: creare progetti, work package, time entries, gestire utenti, leggere report.

Autenticazione

OpenProject supporta autenticazione HTTP Basic con un API token personale. Per generare il token:

  1. Accedi a OpenProject
  2. Vai su “I miei account” → Token di accesso
  3. Clicca “Genera nuovo token”
  4. Copia e conserva il token (non sarà più visibile)

Prima chiamata

# Variabili
OP_URL="https://openproject.tuodominio.it"
OP_TOKEN="d9f3b8c1a2e4..."   # il tuo token

# Autenticazione Basic: base64(TOKEN:x)  (la password è vuota)
curl -u "$OP_TOKEN:x" \
  "$OP_URL/api/v3/projects"

Endpoint principali

  • GET /api/v3/projects — lista progetti
  • POST /api/v3/projects — crea progetto
  • GET /api/v3/projects/{id} — dettaglio progetto
  • GET /api/v3/work_packages — lista work package (filtri con JSON body)
  • POST /api/v3/work_packages — crea work package
  • PATCH /api/v3/work_packages/{id} — aggiorna
  • GET /api/v3/users — lista utenti
  • GET /api/v3/time_entries — ore lavorate
  • GET /api/v3/versions — milestone

Esempio: creare un work package

curl -X POST "$OP_URL/api/v3/work_packages" \
  -u "$OP_TOKEN:x" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Implementare login OAuth2",
    "type": "http://localhost:8080/api/v3/types/1",
    "project": "http://localhost:8080/api/v3/projects/3",
    "assignee": "http://localhost:8080/api/v3/users/4",
    "startDate": "2026-06-15",
    "dueDate": "2026-06-30",
    "estimatedTime": "PT16H",
    "description": {
      "format": "markdown",
      "raw": "## Task\nImplementare provider OAuth2 con Google e GitHub."
    }
  }'

Filtri avanzati

Per filtrare work package, usa POST a /api/v3/work_packages/queries o GET con parametri:

curl -X POST "$OP_URL/api/v3/work_packages/queries" \
  -u "$OP_TOKEN:x" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"status": {"operator": "=", "values": ["open"]}},
      {"assignee": {"operator": "=", "values": ["me"]}}
    ],
    "sortBy": [["dueDate", "asc"]]
  }'

Webhooks

OpenProject supporta webhook per eventi (work package creato, stato cambiato, commento aggiunto). Configurali in Amministrazione → Webhook. Payload JSON inviato in POST all’URL configurato.

Rate limiting

La versione self-hosted non ha rate limit rigidi di default. La versione Cloud ha limiti per piano (Standard: 1000 req/h, Premium: illimitati).

“Con l’API OpenProject ho automatizzato l’allocazione di issue da GitHub: ogni PR crea automaticamente un work package di review.”

Doc completa: API Introduction · Esempi: API docs su GitHub

Torna in alto