Sicurezza
Questo controller è sottoposto alle regole di security del sistema.
Per maggiori dettagli, fare riferimento alla sezione Authentication
Note
Le indicazioni riportate di seguito hanno lo scopo di illustrare le funzionalità e le caratteristiche di questo Web API controller.
Authentication
Token JWT
Al fine di potere invocare le API REST, è necessario ottenere un token di autenticazione tramite l’apposito servizio /Auth/Login.
Per maggiori informazioni fare riferimento all'apposita sezione di questa guida.
Bearer Authentication
La "Bearer Authentication" (tradotta "autenticazione al portatore", detta anche "autenticazione token") è uno schema di autenticazione HTTP che coinvolge un token di sicurezza denominato bearer token.
Per maggiori informazioni fare riferimento all'apposita sezione di questa guida.
Identificazione dell’applicazione chiamante
Alcune delle funzioni delle API REST possono essere utilizzate solamente se (oltre ad una corretta autenticazione dell’utente) si esegue anche una dichiarazione dell’applicazione chiamante.
Per maggiori informazioni fare riferimento all'apposita sezione di questa guida.
Actions & Paths
Di seguito sono elencate le azioni REST eseguibili tramite le Web API.
Le azioni sono raggruppate per "topic".
Clicca un "topic" per visualizzare le diverse azioni in esso contenute.
Ad ogni azione corrisponde un metodo interno alla classe del controller Web API, ed un set di paths di routing utilizzabili per invocarla.
POST: /api/v1/Auth/Activate
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/ChangePassword
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Conflict
Routing template:
/api/{version}/Auth/Conflict
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/GetSwagger
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| honorAcceptLanguageHeader | boolean | NO | Query |
|
| bestPracticeOnly | boolean | NO | Query |
|
Tags:
Produces:
- HTTP 200: object as application/json
- HTTP 200: object as text/json
- HTTP 200: object as application/xml
- HTTP 200: object as text/plain
- HTTP 200: object as application/octet-stream
Response: 200 (Success) object
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/IspAuth
Routing template:
/api/{version}/Auth/IspAuth
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/Limits
Routing template:
/api/{version}/Auth/Limits
Tags:
Produces:
- HTTP 200: IUserLimit as application/json
- HTTP 200: IUserLimit as text/json
- HTTP 200: IUserLimit as application/xml
- HTTP 200: IUserLimit as text/plain
- HTTP 200: IUserLimit as application/octet-stream
Response: 200 (Success) IUserLimit
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Login
Routing template:
/api/{version}/Auth/Login
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Logout
Routing template:
/api/{version}/Auth/Logout
Tags:
Produces:
- HTTP 200: Boolean as application/json
- HTTP 200: Boolean as text/json
- HTTP 200: Boolean as application/xml
- HTTP 200: Boolean as text/plain
- HTTP 200: Boolean as application/octet-stream
Response: 200 (Success) ApiActionResult
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/Me
Routing template:
/api/{version}/Auth/Me
Tags:
Produces:
- HTTP 200: User as application/json
- HTTP 200: User as text/json
- HTTP 200: User as application/xml
- HTTP 200: User as text/plain
- HTTP 200: User as application/octet-stream
Response: 200 (Success) User
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/Menu
Routing template:
/api/{version}/Auth/Menu
Tags:
Produces:
- HTTP 200: IMenuNodeList as application/json
- HTTP 200: IMenuNodeList as text/json
- HTTP 200: IMenuNodeList as application/xml
- HTTP 200: IMenuNodeList as text/plain
- HTTP 200: IMenuNodeList as application/octet-stream
Response: 200 (Success) ApiActionResult>
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/Permits
Routing template:
/api/{version}/Auth/Permits
Tags:
Produces:
- HTTP 200: BooleanIEnumerable as application/json
- HTTP 200: BooleanIEnumerable as text/json
- HTTP 200: BooleanIEnumerable as application/xml
- HTTP 200: BooleanIEnumerable as text/plain
- HTTP 200: BooleanIEnumerable as application/octet-stream
Response: 200 (Success) array of bool
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/PreActivate
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/PreLogin
Routing template:
/api/{version}/Auth/PreLogin
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Recover
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| username | string | NO | Query |
|
| recoverUserId | integer | NO | Query |
|
| recoverCustomerId | integer | NO | Query |
|
Tags:
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Refresh
Routing template:
/api/{version}/Auth/Refresh
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Produces:
- HTTP 400: LoginResult as application/json
- HTTP 400: LoginResult as text/json
- HTTP 400: LoginResult as application/xml
- HTTP 400: LoginResult as text/plain
- HTTP 400: LoginResult as application/octet-stream
- HTTP 400: LoginResult as text/xml
Response: 400 (Bad Request) LoginResult
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Session
Routing template:
/api/{version}/Auth/Session
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
GET: /api/v1/Auth/Stats
Routing template:
/api/{version}/Auth/Stats
Tags:
Produces:
- HTTP 400: UsageStats as application/json
- HTTP 400: UsageStats as text/json
- HTTP 400: UsageStats as application/xml
- HTTP 400: UsageStats as text/plain
- HTTP 400: UsageStats as application/octet-stream
Response: 400 (Bad Request) UsageStats
Samples
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/Token
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| request | TokenRequest | NO | Query |
|
Tags:
Response:
Samples
Download HTTP 200 response sample
Download Postman collection sample
Provalo !
POST: /api/v1/Auth/ValidatePassword
Parameters:
| Name | Type | Required | In | Features |
|---|---|---|---|---|
| token | string | NO | Query |
|
Tags:
Consumes:
- application/json
- application/xml
- text/plain
- application/json-patch+json
- text/json
- application/*+json
- text/xml
- application/*+xml
Response:
Samples
Download Postman collection sample
Provalo !
Definizioni
Le definizioni a seguire descrivono la struttura dei datamodels coinvolti nelle diverse operazioni REST eseguibili per questo controller.
Alcune definizioni sono sottoposte a serializzazione polimorfica, e pertanto il loro schema polimorfico completo viene riportato.
| Name | Description |
|---|---|
| Brand | Brand |
| Capabilities | Capabilities |
| ConflictSessionRequest | Conflict Session Request |
| CredentialsRequest | Credentials Request |
| IMenuNode | Menu Node |
| IUserLimit | User Limit |
| JToken | J Token |
| LoginResult | Login Result |
| MessageCode | Message Code |
| PasswordChangePayload | Password Change Payload |
| RefreshTokenRequest | Refresh Token Request |
| SecurityPageMenu | Security Page Menu |
| SecurityPolicyRule | Security Policy Rule |
| TokenRequest | Token Request |
| UsageStats | Usage Stats |
| User | User |
Errori
Le actions del controller possono generare errori per i seguenti casi:
- Stato 400: query mal strutturate (es. parametri codificati non correttamente)
- Stato 401: errori di autenticazione (es. chiavi o credenziali non riconosciute)
- Stato 403: Proibito. La richiesta era valida, ma il server rifiuta l'azione. L'utente potrebbe non disporre delle autorizzazioni necessarie per una risorsa o potrebbe aver bisogno di un account di qualche tipo.
- Stato 404: Non trovato, o risorsa sconosciuta
- Stato 409: Conflitto. Indica che la richiesta non può essere elaborata a causa di conflitti nello stato corrente della risorsa, ad esempio un conflitto di modifica tra più aggiornamenti simultanei.
- Stato 500: Errore interno del del server
Gli errori sono formattati in JSON
Versioning
E’ possibile selezionare la versione dei web services tramite il token {version}
/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
Il token {version} può contenere sia valori “esatti”, sia l’alias speciale “latest”, che identifica la versione più recente tra quelle esistenti nel sistema.
In linea generale si raccomanda vivamente l’utilizzo dell’alias speciale “latest”.
Qualora si desideri essere particolarmente “conservativi” ed aderenti ad una specifica versione, specificarne il nome in modo esplicito (es. “v1”).
Routing
Il sistema utilizza la seguente sintassi di routing, costituita da una sequenza di "path-tokens" (i parametri della request):
{schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}
I tokens identificano rispettivamente:
- {host} -> HOST dell’URL
- {version} -> versione dei web services
- {controller} -> nome del servizio (controller) che si desidera invocare
- {details} -> livello opzionale di dettaglio del JSON ritornato (se pertinente)
- {action} -> azione opzionale (metodo) invocata nel controller
- {id} -> singolo argomento opzionale (parametro) di primary key del metodo nel controller, qualora esso lo preveda
- {querystring} -> parametri aggiuntivi ed eventuali "modificatori" del processo di elaborazione e serializzazione
OData
Le API REST sono internamente basate sulla tecnologia Microsoft WebAPI, e sono largamente compliant con le specifiche REST, OData v3 e OData v4.
Funzioni ed approfondimenti relativi a OData
Per maggiori approfondimenti e dettagli relativi ai criteri generali d'uso delle funzioni OData, fare riferimento alla guida di base sull'argomento
Opzioni
Le funzioni delle API REST implementate in CRM in Cloud includono un vasto set di opzioni che consentono di adattare struttura e forma dei pacchetti JSON in base alle proprie esigenze e preferenze.
Al contrario dei parametri, che vengono specificati nella route dell’URL (attraverso i tokens e la querystring), le opzioni devono invece essere passate tramite gli headers HTTP della request.
Come da RFC6648 tutte le opzioni passate tramite headers HTTP hanno nel proprio nome il prefisso custom “Crm-”.
Qualora una certa opzione non venga specificata, il sistema utilizzerà il valore di default specifico alla {version} indicata nell’URL.
Per una disquisizione completa relativa alle opzioni ed alla serializzazione polimorfica, fare riferimento alla guida generale sull'argomento
Swagger
Di seguito è possibile scaricare il descrittore JSON in formato Swagger/OpenAPI