🔌 Esempio: API Documentation 🔌 Example: API Documentation

Estratto dalla documentazione API del progetto Errantia Excerpt from the Errantia project API documentation

API Base URL: https://api.errantia.net/v1
Versione: 1.0
Formato: JSON
Autenticazione: JWT Bearer Token
Gestito con: MdExplorer + Git

API Base URL: https://api.errantia.net/v1
Version: 1.0
Format: JSON
Authentication: JWT Bearer Token
Managed with: MdExplorer + Git

Panoramica

Le API di Errantia permettono di gestire oggetti erranti, avvistamenti e profili artigiani. Tutte le richieste e risposte utilizzano formato JSON. L'autenticazione avviene tramite JWT token.

Autenticazione

POST /auth/login

🔓 Autenticazione NON richiesta

Effettua il login di un artigiano e restituisce un access token JWT valido per 24 ore.

Request Body

Parametro	Tipo	Obbligatorio	Descrizione
email	string	Sì	Email dell'artigiano
password	string	Sì	Password (min 8 caratteri)

              Request Example
{
  "email": "artigiano@test.com",
  "password": "test123"
}
            

Responses

200 OK - Login riuscito

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "artigiano@test.com",
      "role": "artisan",
      "profile": {
        "businessName": "Bottega del Test"
      }
    }
  }
}
            

401 Unauthorized - Credenziali errate

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email o password non corretti"
  }
}
            

cURL Example

curl -X POST https://api.errantia.net/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "artigiano@test.com", "password": "test123" }'

Gestione Oggetti

POST /artisans/objects

🔒 Autenticazione richiesta

Crea un nuovo oggetto errante. L'artigiano deve essere autenticato e verificato. Il sistema genera automaticamente un codice univoco e l'URL NFC.

Headers

Header	Valore	Descrizione
Authorization	Bearer {token}	JWT token ottenuto dal login
Content-Type	application/json	Formato della richiesta

Request Body

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome oggetto (max 100 caratteri)
message	string	Sì	Messaggio/dedica (max 500 caratteri)
description	string	No	Descrizione dettagliata (max 2000 caratteri)

              Request Example
{
  "name": "Pietra del Viandante",
  "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
  "description": "Pietra levigata dal fiume Arno"
}
            

Responses

201 Created - Oggetto creato con successo

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "uniqueCode": "ABC123",
    "nfcUrl": "https://errantia.net/e/ABC123",
    "name": "Pietra del Viandante",
    "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
    "sightingsCount": 0,
    "createdAt": "2024-12-31T10:00:00Z"
  }
}
            

400 Bad Request - Dati non validi

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Nome oggetto obbligatorio",
    "fields": {
      "name": "Campo obbligatorio"
    }
  }
}
            

401 Unauthorized - Token mancante o non valido

403 Forbidden - Artigiano non verificato

cURL Example

curl -X POST https://api.errantia.net/v1/artisans/objects \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "name": "Pietra del Viandante", "message": "Lascia che questa pietra porti fortuna nel tuo cammino", "description": "Pietra levigata dal fiume Arno" }'

GET /objects/:code

🔓 Autenticazione NON richiesta

Recupera le informazioni pubbliche di un oggetto errante tramite il suo codice univoco. Questa API è chiamata dalla landing page NFC quando un utente scansiona il tag.

Path Parameters

Parametro	Tipo	Descrizione
code	string	Codice univoco dell'oggetto (es. ABC123)

Responses

200 OK - Oggetto trovato

{
  "success": true,
  "data": {
    "uniqueCode": "ABC123",
    "name": "Pietra del Viandante",
    "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
    "artisan": {
      "businessName": "Bottega del Test"
    },
    "sightingsCount": 5,
    "lastSighting": {
      "locationName": "Firenze, Italia",
      "createdAt": "2024-12-30T15:30:00Z"
    }
  }
}
            

404 Not Found - Oggetto non esistente

{
  "success": false,
  "error": {
    "code": "OBJECT_NOT_FOUND",
    "message": "Oggetto con codice ABC123 non trovato"
  }
}
            

cURL Example

curl https://api.errantia.net/v1/objects/ABC123

Codici di Stato HTTP

Codice	Significato	Quando viene usato
200	OK	Richiesta GET riuscita
201	Created	Risorsa creata con successo (POST)
400	Bad Request	Dati di input non validi
401	Unauthorized	Token mancante o non valido
403	Forbidden	Accesso negato (es. artigiano non verificato)
404	Not Found	Risorsa non trovata
500	Internal Server Error	Errore generico del server

Benefici dello Spec Driven Development

Questa documentazione API è la single source of truth per frontend e backend:

✓ File docs/ANALISI_TECNICA.md versionato in Git
✓ Backend implementa esattamente gli endpoint documentati
✓ Frontend consuma le API seguendo gli esempi nella documentazione
✓ Le modifiche alle API richiedono prima l'aggiornamento della spec
✓ I tester usano gli esempi cURL per validare le API
✓ Export PDF per condivisione con stakeholder esterni
✓ Link diretti ai requisiti funzionali (es. RF-AUTH-01 → POST /auth/login)

Overview

The Errantia APIs allow managing wandering objects, sightings, and artisan profiles. All requests and responses use JSON format. Authentication is done via JWT token.

Authentication

POST /auth/login

🔓 Authentication NOT required

Performs artisan login and returns a JWT access token valid for 24 hours.

Request Body

Parameter	Type	Required	Description
email	string	Yes	Artisan email
password	string	Yes	Password (min 8 characters)

              Request Example
{
  "email": "artigiano@test.com",
  "password": "test123"
}
            

Responses

200 OK - Login successful

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "artigiano@test.com",
      "role": "artisan",
      "profile": {
        "businessName": "Bottega del Test"
      }
    }
  }
}
            

401 Unauthorized - Invalid credentials

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}
            

cURL Example

curl -X POST https://api.errantia.net/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "artigiano@test.com", "password": "test123" }'

Object Management

POST /artisans/objects

🔒 Authentication required

Creates a new wandering object. The artisan must be authenticated and verified. The system automatically generates a unique code and NFC URL.

Headers

Header	Value	Description
Authorization	Bearer {token}	JWT token obtained from login
Content-Type	application/json	Request format

Request Body

Parameter	Type	Required	Description
name	string	Yes	Object name (max 100 characters)
message	string	Yes	Message/dedication (max 500 characters)
description	string	No	Detailed description (max 2000 characters)

              Request Example
{
  "name": "Pietra del Viandante",
  "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
  "description": "Pietra levigata dal fiume Arno"
}
            

Responses

201 Created - Object created successfully

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "uniqueCode": "ABC123",
    "nfcUrl": "https://errantia.net/e/ABC123",
    "name": "Pietra del Viandante",
    "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
    "sightingsCount": 0,
    "createdAt": "2024-12-31T10:00:00Z"
  }
}
            

400 Bad Request - Invalid data

401 Unauthorized - Missing or invalid token

403 Forbidden - Artisan not verified

cURL Example

GET /objects/:code

🔓 Authentication NOT required

Retrieves public information about a wandering object by its unique code. This API is called by the NFC landing page when a user scans the tag.

Path Parameters

Parameter	Type	Description
code	string	Unique object code (e.g., ABC123)

Responses

200 OK - Object found

{
  "success": true,
  "data": {
    "uniqueCode": "ABC123",
    "name": "Pietra del Viandante",
    "message": "Lascia che questa pietra porti fortuna nel tuo cammino",
    "artisan": {
      "businessName": "Bottega del Test"
    },
    "sightingsCount": 5,
    "lastSighting": {
      "locationName": "Firenze, Italia",
      "createdAt": "2024-12-30T15:30:00Z"
    }
  }
}
            

404 Not Found - Object does not exist

cURL Example

curl https://api.errantia.net/v1/objects/ABC123

HTTP Status Codes

Code	Meaning	When used
200	OK	Successful GET request
201	Created	Resource created successfully (POST)
400	Bad Request	Invalid input data
401	Unauthorized	Missing or invalid token
403	Forbidden	Access denied (e.g., unverified artisan)
404	Not Found	Resource not found
500	Internal Server Error	Generic server error

Benefits of Spec Driven Development

This API documentation is the single source of truth for frontend and backend:

✓ File docs/ANALISI_TECNICA.md versioned in Git
✓ Backend implements exactly the documented endpoints
✓ Frontend consumes APIs following the documentation examples
✓ API changes require spec updates first
✓ Testers use cURL examples to validate APIs
✓ PDF export for sharing with external stakeholders
✓ Direct links to functional requirements (e.g., RF-AUTH-01 → POST /auth/login)

← Torna al Case Study ← Back to Case Study