Basic Operations

TS Enterprise Smart WebApi Services è un ecosistema di webservice che segue i principi architetturali REST, e si fonda su poche semplici regole generali.

Di seguito è riportata una panoramica dei principi fondamentali dell’architettura di tipo REST, insieme ad alcuni dettagli su come questi principi.

Definizione di risorse sotto forma di URL

Basato su protocollo HTTP.

E' possibile interrogare il servizio attraverso semplici richieste HTTP, utilizzando client basati su qualsiasi tecnologia: web browser, client C#, java, python, javascript, sistemi operativi windows o linux.

Ogni URL definisce univocamente l’accesso ad una risorsa dati.

Sono gli URL che identificano su che tipo di dato si sta operando:

https://tse.smart-api.teamsystem.cloud/api/{product}/{version}/company/{companyId}/customer/{customerId}

Lato consumer le api sono messe a disposizione attraverso un unico endpoint l'istradamento verso la relativa risorsa è automatico.

Ogni risorsa è organizzata per modulo. L'esplicita indicazione del modulo permette di instradare la richiesta verso il corretto servizio di riferimento.

Ad esempio, assumendo il servizio web api in ascolto all’url “root”:

https://tse.smart-api.teamsystem.cloud/api/{product}/{version}/company/{companyId}

Le differenti funzionalità esposte dal servizio sono esposte come URL basati su questa root.

Di seguito alcuni esempi:

• /document url risorsa per TUTTE le possibili operazioni sui documenti
• company/{companyId}/ url risorsa per TUTTE le possibili operazioni sulle ditte e le sue sottoentita
• /company/{companyId}/customer url risorsa per TUTTE le possibili operazioni sui clienti

Naming conventions

Per convenzione, ogni risorsa assume di default il nome dell’entità stessa, in inglese.

Autenticazione

Si veda la sezione AUTENTICAZIONE per informazioni su come accedere agli ambienti disponibili.

Rispetto della semantica e dei comandi HTTP

Definita una risorsa sotto forma di URL, le operazioni possibili su quella risorsa sono legate all’URL della risorsa stessa e ai metodi HTTP utilizzata dal chiamante.

Ad esempio:

• GET: recupera la risorsa, ovvero il DTO configurato con chiave specificata in URL
• PUT: modifica la risorsa con chiave specificata in URL, nel body sarà presente lo stesso DTO ritornato dalla GET, con le opportune proprietà modificate
• DELETE: elimina la risorsa con chiave specificata in URL
• POST: crea un nuovo elemento della risorsa e ritorna il relativo DTO
• PATCH: modifica solo una specifica proprietà del DTO, non c'è quindi la necessità di inoltrare tutto il DTO nel body ma solo la/le proprietà da aggiornare. Nel caso si volesse modificare la/le proprietà di un elemento di una collezione relazionata internamente, è necessario specificare anche le chiavi dell'entità relazionata, oltre le proprietà che si intende modificare.

Quando si parla di “recupera”, “modifica”, “elimina” e “crea” si intendono le relative operazioni implementate dallo specifico Biz che gestisce l’aggregato. Ogni operazione offerta da Enterprise WebAPI deve essere considerata come “esposizione verso client esterni tramite servizi REST” di operazioni di business, a meno di casi particolari.

NOTE: si noti la differente semantica della operazione POST, che non richiede di specificare l’id nell’URL, a differenza delle altre operazioni GET, PUT e DELETE. Di fatto, la POST viene utilizzata per tutte le operazioni che non lavorano direttamente su una risorsa esistente, come:

warning

I metodi HTTP HEAD, CONNECT, OPTIONS, TRACE non sono utilizzati.

Risorse autodescrittive

Come accennato in precedenza, ogni operazione di lettura/scrittura su una risorsa opera su un DTO, ovvero un Data Transfer Object specificatamente definito per disaccoppiare la rappresentazione della risorsa esposta ai client esterni

Il formato di serializzazione del DTO da utilizzare come interscambio può essere definito dal client che interroga il servizio aggiungendo alla richiesta l’header HTTP “Accept”, e sono supportati due valori:

• application/json: serializzazione JSON; è il valore di default utilizzato in caso che l’header “Accept” non sia specificato dal chiamante

La risposta del servizio contiene, nel suo header “Content-Type” il formato di serializzazione, ovvero:

• application/json: serializzazione JSON; è il valore di default utilizzato in caso che l’header “Accept” non sia stato specificato dal chiamante

encoding

Viene ritornato anche l’encoding utilizzato (in genere utf-8), ad esempio:

REQUEST  => Accept: application/json
RESPONSE => Content-Type: application/json; charset: utf-8

Localizzazione

Anche il supporto multilingua è gestito tramite header HTTP; in particolare, specificando l’header “Accept-Language” con un valore specifico in standard RFC 4646, la sessione applicativa viene inizializzata utilizzando le informazioni di globalizzazione specificate.

REQUEST  => Accept-Language: en-US
RESPONSE => Content-Language: en-US

Protocollo stateless

In rispetto del protocollo HTTP, ogni richiesta proveniente dai client è processata in modo completamente stateless, ovvero una qualsiasi richiesta non ha relazione con le precedenti richieste effettuate dallo stesso chiamante. Una singola richiesta deve quindi contenere TUTTE le informazioni necessarie per poter eseguire l’operazione desiderata, a partire dalle informazioni di autenticazione e di creazione della sessione utente.

Nel caso di una richiesta GET occorre specificare:

• Tipo di autenticazione: obbligatorio
• Credenziali: obbligatorie

Sicurezza ed idempotenza

Si definisce un metodo come SAFE – sicuro - quando la relativa richiesta non altera in alcun modo lo stato della risorsa stessa e di eventuali risorse collegale: si parla quindi più genericamente di metodi SAFE in quanto non alterano lo stato del server.

I metodi GET sono SAFE, possono quindi essere chiamati innumerevoli volte senza preoccuparsi di “side effects”, mentre i metodi PUT E DELETE non sono SAFE per definizione: ogni PUT modifica la relativa risorsa (a meno di passare sempre la stessa rappresentazione, ma anche in questo caso potrebbero essere diversi alcuni campi autogenerati), mentre la DELETE elimina la risorsa rendendola non più disponibile.

Il metodo POST ha un comportamento dipendente dal tipo di operazione implementata; il metodo POST non è SAFE relativamente

Si definisce un metodo come IDEMPOTENT – idempotente – se non vi è alcuna differenza nello stato del server tra l’esecuzione di una richiesta singola o N richieste multiple della stessa identica richiesta.

Il metodo GET è quindi idempotente perché, al netto di processi esterni di modifica del dato in lettura, lo stato del server rimane invariato indipendentemente dal numero di richieste effettuate (non si considerano logging e processi interni come contatori o altro). I metodi PUT e DELETE sono anch’essi idempotenti perché lo stato del server viene alterato solo alla prima richiesta di eliminazione o modifica mentre le successive non modificano (o non dovrebbero modificare) lo stato del server.

Il metodo POST non è genericamente considerato idempotente: non lo è per l’operazione “Create” (ad ogni richiesta viene creata una risorsa distinta)

Schema generale

Per ogni risorsa esposta dal servizio, il framework mette a disposizione una serie di operazioni per il CRUD

L’URL di base di tutte chiamate è il seguente: https://tse.smart-api.teamsystem.cloud

• {product}: sigla corrispondente al prodotto di destinazione
• {version}: v1, versione dei servizi

PORTA

Il parametro porta è opzionale, per accedere ai servizi bisogna usare https che corrisponde alla porta 443.