Standard della piattaforma

Riguardo a coding, contribuzioni, eventi, API

Event fields

Producers

Nella piattaforma si fa ampio uso del Pattern Event Sourcing è quindi fondamentale che il formato degli eventi sia stabile e documentato.

Per ogni evento i producers DEVONO inserire sempre i seguenti dati:

Campo	Valore	Formato	Annotazioni
id	identificativo unico dell'entità oggetto dell'evento	UUID	Es: in un pagamento è l'ID del pagamento, in una pratica è l'application_id etc...
event_id	identificativo unico dell'evento	UUID	Non deve esserci per nessun motivo due volte lo stesso ID
event_version	versione dell'evento	Integer or Float	E' un intero (Es: 1, 2, etc..) cambia ad ogni cambiamento NON retrocompatibile.
event_created_at	data dell'evento	ISO8601	Ricordarsi di usare il formato della timezone Europe/Rome (Es: 2022-06-22T15:11:20+02:00)
app_id	Nome e versione dell'applicativo che ha generato l'evento	$application:$version	Utile per motivi di debug (Es: payment-dispatcher:1.0.15).

Attenzione: se si genera un evento, a partire da un evento esistente, si sta creando una nuova entità che avrà i propri valori event_id, event_created_at, event_version, app_id: non si deve mai ricopiare questi valori dall'evento originario.

Consumers

I consumatori devono essere sempre attenti alla versione di eventi che supportano: la versione deve essere esplicitamente supportata ed eventi di una versione non supportata devono essere scartati

Nei log è possibile dare evidenza del fatto che si è incontrato un evento non supportato, ma non va loggato come errore è sufficiente dare l'informazione a livello DEBUG. In condizioni normali un servizio che consuma eventi emette una riga di log a livello INFO se e solo se ha gestito l'evento e ha fatto qualcosa con quell'evento che ha avuto successo.

Standard Date

Le date vanno sempre espresse nello standard ISO8601, in particolare, le date non devono contenere i millisecondi, e devono contenere il formato della timezone Europe/Rome. Le letter T e Z DEVONO essere espresse in maiuscolo.

Es: 2022-06-22T15:11:20+02:00

API Standards

Facciamo in generale riferimento alle linee guida di Zalando, tenendo ovviamente in considerazione anche i requisiti e le raccomandazioni delle Linee Guida di Interoperabilità della PA.

• i servizi DEVONO agire solo su verbi HTTP supportati, rispettarne la semantica, restituire errore sugli altri.

• i metodi DELETE, GET, HEAD, OPTIONS, PUT, TRACE devono essere idempotenti (vd anche RFC7231)

• le API hanno path al plurale sulle collezioni, per separare le parole si usa il kebab-case (il trattino).

• nelle risposte le URL dovrebbero essere sempre espresse in modo assoluto

POST    /tenants
GET     /tenants/{tenant_id}
PUT     /tenants/{tenant_id}
PATCH   /tenants/{tenant_id}
DELETE  /tenants/{tenant_id}

GET

• Le collezioni devono essere facilmente navigabili, per questo abbiamo adottato il seguente standard:

{
    "meta": {
        "page": {
            "offset": 5000,
            "limit": 20,
            "sort": "creationTime"
        },
        "total": 46561
    },
    "links": {
        "self": "http..../items?offset=5000&limit=20&sort=creationTime",
        "prev": "http..../items?offset=4980&limit=20&sort=creationTime",
        "next": "http..../items?offset=5020&limit=20&sort=creationTime"
    },
    "data": [
        { "id": "..." },
        { "id": "..." },
        { "id": "..." }
    ]
}

Pagination

• Le GET sulle risorse devono USARE laddove supportati i query parameters convenzionali:

• sort

• offset

• limit

• cursor

• embed

• q

• fields

Pagination/2

• Su alcuni campi è utile implementare anche l'opzione di paginazione cursor-based:

GET /payments?created_since=$timeStamp

error handling

{ 
    "errors": [
        {
            "type": "/errors/incorrect-user-pass",
            "title": "Incorrect username or password.",
            "status": 401,                                         (optional)
            "detail": "Authentication failed due to incorrect username or password.",
            "instance": "/login/log/abc123"                        (optional)
        },
        ...
    ]
}

Fare riferimento alla RFC 7807