2.4.1. Indicazioni di utilizzo¶

L’interfaccia di servizio REST deve utilizzare l’HTTP verb più adatto all’operazione come indicato in RFC 7231 [59]. In particolare i metodi:

• GET, HEAD, DELETE: non devono avere un payload.
• GET, HEAD: devono essere «safe», cioè devono essere essenzialmente read-only. Il client in questo caso non si aspetta e non richiede un cambiamento dello stato della risorsa.
• GET, HEAD, PUT, DELETE: devono essere idempotenti, cioè chiamate multiple con richieste identiche si comportano come singole richieste.
• POST: dovrebbe implementare un meccanismo di idempotenza per evitare di duplicare eventuali entry.

Ove necessario, specialmente ai fini del caching e l’accesso concorrente alle risorse [60], occorre fare leva sugli ETag [61] (degli identificatori univoci di versione delle risorse). Infine l’utilizzo di eventuali header HTTP non deve sostituire i parametri da passare in una GET.

2.4.2. Sicurezza¶

Lo standard di riferimento per la firma e la crittografia in ambito JSON/REST è Javascript Object Signing and Encryption [62] (di seguito JOSE), menzionato nelle Linee Guida AgID [63] ed in «European Telecommunications Standards Institute - Security of the mission critical service» [64]. JOSE è un framework per la sicurezza comprendente diverse componenti tra cui centrale è il JSON Web Token [65] (di seguito JWT). JWT è uno standard per la definizione di token di accesso basato su JSON Web Signature [66] (di seguito JWS)) e JSON Web Encryption [67] (si seguito JWE) di cui eredita ed estende gli header. Il token JWT è passato in REST tramite l’header HTTP Authorization utilizzando lo schema Bearer [68]. Il token in OpenID Connect è espresso per esempio direttamente come JWT.

Per ulteriori dettagli sulla sicurezza, si vedano anche:

• OWASP REST Security Cheat-Sheet [69];
• OWASP API Security Project [70];
• JWS - Security Considerations [71].

2.4.3. Uniformità e Naming¶

In questa sezione introduciamo le best practice da utilizzare per interfacce di servizio REST. In prima istanza, ogni endpoint deve essere univocamente associato alle componenti Scheme, Authority e Path di un URL [72].

La componente Authority dell’URL:

• dovrebbe essere associata al dominio del sito Istituzionale dell’erogatore presente su IndicePA, anche tramite il prefisso «api», ad esempio un erogatore con sito istituzionale «erogatore.gov.it», potrebbe usare come authority «api.erogatore.gov.it»;
• può essere associata al dominio di un ente che l’erogatore ha delegato (ad es., una società in-house, un consorzio di comuni).

Per quanto riguarda la componente Path, i nomi utilizzati non devono usare abbreviazioni e acronimi non universalmente riconosciuti [73]. Inoltre, il Path dovrebbe essere semplice, intuitivo e coerente [74].

Il campo Query dovrebbe:

• essere in snake_case minuscolo;
• non essere in camelCase;
• utilizzare ove possibile dei nomi comuni per le funzionalità di paginazione, ricerca ed embedding/resource-expansion (ad es., limit, offset, q, sort).

Le risposte in formato JSON [75], devono restituire sempre oggetti strutturati con attributi chiave-valore, non semplici liste. Questo permette di estendere facilmente le risposte introducendo in versioni successive ulteriori attributi (ad es., di paginazione).

In caso di errore, le risposte devono usare schemi standard come quello definito nella RFC 7807 - Problem Details for HTTP APIs - IETF Tools [76] in particolare utilizzando il content type application/problem+json nella risposta.

Quando le risorse contengono link e riferimenti a risorse esterne, si dovrebbero usare le specifiche indicate in IANA registered link relations [77].

Tutti i riferimenti dovrebbero contenere URL comprensivi di schema.

2.4.4. Throttling ed indisponibilità del servizio¶

Nelle API basate su REST, meccanismi di throttling vengono implementati al fine di garantire l’accessibilità delle interfacce di servizio ed evitare in alcuni casi la raccolta non autorizzata (web-harvesting_) dei dati.

Poiché l’RFC 6585 prevede per la gestione del throttling il solo status code 429, nel Modl2018 si richiede di notificare al fruitore lo stato del throttling ed eventuali limiti come segue:

• restituire in ogni risposta valida i valori globali di throttling tramite i seguenti header HTTP:

  • X-RateLimit-Limit: limite massimo di richieste per un endpoint;
  • X-RateLimit-Remaining: numero di richieste rimanenti fino al prossimo reset;
  • X-RateLimit-Reset: il numero di secondi mancanti al momento in cui il limite verrà reimpostato.

• utilizzare gli HTTP status code nelle risposte:

  • HTTP 429 (too many requests), insieme ai rate limit di cui al punto precedente, se il rate limit viene superato;
  • HTTP 503 (service unavailable) se l’infrastruttura non può erogare le operazioni offerte nei tempi attesi (definiti dalla SLA associata all’interfaccia di servizio).

• nei casi 429 e 503 gli erogatori dovrebbero notificare al client dopo quanti secondi ripresentarsi tramite l’header Retry-After [78] (pratica anche detta “circuit breaker”), anche implementando meccanismi di exponential back-off. L’RFC prevede che questo header possa essere utilizzato sia in forma di data che di secondi, ma il Modl2018 vieta l’utilizzo del formato data poiché se non implementato correttamente potrebbe aggravare lo stato dei sistemi.

I fruitori dell’interfaccia di servizio devono impegnarsi a rispettare le indicazioni provenienti dagli header ed dagli status code di cui sopra.