Standard della piattaforma

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 ci aspettiamo almeno i seguenti campi:

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.

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.

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

API Standards

Facciamo in generale riferimento alle linee guida di Zalando:

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 supportare i query parameters convenzionali:

• sort

• offset

• limit

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