best practices per lo sviluppo delle applicazioni 

Rest Api Service (AGID Summary)

Regolamentazione per l'implementazioni di servizi rest

Le API DEVONO essere rappresentate mediante un Interface Description Language standard (IDL). Nello specifico: per REST, OpenAPI 3.0 e successive; 

La versione del servizio

http(s)://hostname/v<major>/<NomeAPI>  

  • v<major>indica il numero di versione in coerenza con Semantic Versioning [2,3]; 
  • <NomeAPI> è il nome della specifica API. 


Le date DEVONO essere conformi: 

  • alla sintassi "full-date" indicata in RFC 3339, ad esempio 2015-05-28 se si indica una data; 
  • alla sintassi "date-time" indicata in RFC 3339, ad esempio 2015-05-28T14:07:17Z o nel formato UNIX Timestamp definito in "The Open Group Base Specifications Issue 7, Rationale: Base Definitions, section A.4 General Concepts" se si indica un momento esatto nel tempo. 

RFC 3339 permette di indicare una timezone prefissando la data con la distanza da UTC: 

  • 2015-05-28T14:07:17+01:00 
  • 2015-05-28T14:07:17-05:00 


Quando la data è specificata in UTC occorre utilizzare sempre il suffisso Z (Zulu time zone): 

  • 2015-05-28T14:07:17Z 


Le proprietà DOVREBBERO avere una nomenclatura consistente. 

Scegliere uno dei due stili di seguito e modificarlo in ASCII: 

  • snake_case 
  • camelCase 


Non usare contemporaneamente snake_case e camelCase nella stessa API. 

Si 
{ "givenName": "Mario", "familyName": "Rossi" }
No 
{ "given_name": "Mario", "familyName": "Rossi" }
Response di una api rest

il payload di una response contenente una entry ritorna un oggetto:

Response 
{ "given_name": "Paolo", "last_name": "Rossi", "id": 313 }

il payload di una response contenente più entry ritorna un oggetto contenente una lista e non direttamente una lista:

Response 
{ 
	"items":[ 
		{ 
			"given_name":"Carlo", 
			"family_name":"Bianchi", 
			"id":314 
		}, 
		{ 
			"given_name":"Giuseppe", 
			"family_name":"Verdi", 
			"id":315 
		} 
	] 
}

DEVONO usarsi le seguenti convenzioni di rappresentazione: 

  • I booleani non DEVONO essere null. 
  • Gli array vuoti non DEVONO essere null, ma liste vuote, ad es. []. 
  • Le enumeration DEVONO essere rappresentate da stringhe non nulle. 
Naming
  • I metodi HTTP DEVONO essere utilizzati rispettando la semantica indicata in RFC 7231 section-4.3.

  • Le response DOVREBBERO restituire URI assoluti, al fine di indicare chiaramente al client l’indirizzo delle risorse di destinazione e non obbligare i client a fare «inferenza» dal contesto. 

  • In caso di errori si DEVONO ritornare: 
    • un payload di tipo Problem definito in RFC 7807 
    • il media type application/problem+json 
    • uno status code esplicativo 
    • l’oggetto, possibilmente esteso 
  • Dopo aver validato il contenuto delle richieste si DEVE ritornare: 
    • HTTP status 415 Unsupported Media Type se il Content-Type non è supportato; 
    • HTTP status 400 Bad Request o HTTP status 404 Not Found se si ipotizza che la richiesta sia malevola; 

    • HTTP status 422 Unprocessable Entity se la representation contenuta nella richiesta è sintatticamente corretta ma semanticamente non processabile. 

  • Si consiglia di differenziare il nome delle collezioni e delle risorse. Questo permette di separare a livello di URI, endpoint che sono in larga parte funzionalmente differenti. 

    • GET /documento/21314123 

    • GET /documenti?data=2018-05-01 

  • Nella definizione dei path si DEVE utilizzare il separatore «-» (kebab-case). 

    /tax-code/{tax_code_id} 

Ottimizzare l’uso della banda e migliorare la responsività

Si DOVREBBERO utilizzare: 

  • tecniche di compressione; 
  • paginazione; 
  • un filtro sugli attributi necessari; 
  • le specifiche di optimistic locking (HTTP header ETag, if-(none-)match) RFC 7232. 

È possibile ridurre l’uso della banda e velocizzare le richieste filtrando i campi delle risorse restituite 

GET https://api.example.org/resources/123 HTTP/1.1

GET /resources/123?fields=(name,partner(name)) HTTP/1.1 (permette di specificare I campi in uscita)


Esposizione dello stato del servizio rest

L'API DEVE esporre lo stato del servizio al path `/status` e ritornare un oggetto con media-type problem+json (RFC 7807). Se il servizio funziona correttamente l'HTTP status è 200. 

Nove Applicazione


Applicazioni Legacy






  • No labels