Passa al contenuto principale
Versione: 2025.003.000 (beta)

Read

GET​

GET risorsa ById​

Per effettuare una lettura di una risorsa per chiave, occorre richiedere in GET la risorsa specificando l’id/chiave:

  • La configurazione della richiesta HTTP come GET.
  • L’URL completo, composto nell’ordine da:
    • server: variabile in base alla configurazione del server.
    • porta: variabile in base alla configurazione del server.
    • rootPath: tse_webapi, NON variabile.
    • versione: v1, NON variabile.
    • modulo: sigla, variabile in base all'appartenenza della risorsa interrogata.
    • ambiente: variabile in base a quale, tra gli ambienti precedentemente configurati, si desidera accedere.
    • risorsa: variabile in base al nome della risorsa che si desidera interrogare.
    • id: variabile in funzione della chiave della risorsa che si vuole interrogare.
  • I parametri specificati in QueryString, ovvero:
    • user (opzionale): variabile in funzione dell’utente applicativo da impersonare, se non specificato vale l'utente autenticato.
    • company: variabile in funzione della azienda di lavoro da utilizzare.
  • Gli headers HTTP impostati, la cui configurazione è stata descritta in precedenza.
    • http://webapi_base_url/v1/ambiente/modulo/risorsa/id?company=XX&user=YYY

La risposta ottenuta, mostrata nell’immagine qui sopra, è composta da:

  • status: 200 OK, variabile in base al tipo di richiesta e al risultato dell’esecuzione (vedi la lista delle richieste disponibili, descritta precedentemente).
  • headers: informazioni sulla risposta ottenuta.
  • body: il contenuto vero e proprio della risposta, in formato JSON (di default) o XML.

GET: webapi_base_url/v1/production/{modulo}/{risorsa}/{id}

Parametri​

  • id: codice identificativo della risorsa da leggere

Codici risposta​

  • 200: l'oggetto {risorsa}DTO richiesto
  • 404: se l'oggetto non è stato trovato

Ricerca risorsa​

Per effettuare una ricerca dati relativamente ad una risorsa, occorre richiedere in POST l’operazione di ricerca sulla risorsa specificando il filtro di ricerca da utilizzare.

  • http://server:porta/rootPath/v1/ambiente/modulo/risorsa/search?company=XX&user=YYY

Si notino le differenze rispetto alla GET precedentemente descritte:

  • La configurazione della richiesta HTTP ora è in POST.
  • L’URL completo NON dichiara il parametro id, che NON DEVE essere specificato: si sta operando infatti su tutte le entità esistenti, e non su una anagrafica specifica.
  • Il parametro aggiuntivo, il cui valore search è NON variabile in quanto definisce univocamente l’operazione di ricerca.
  • Il body della richiesta definisce un filtro specifico, singolo o multiplo sulle proprietà d'interesse.
{
  "filters": {
    "items": [
      {
        "comparer": 30,
        "operator": 0,
        "propertyName": "numdocorig",
        "value": "51"
      }
    ]
  }
}

La risposta ottenuta, è composta da:

  • status: stato di ritorno della richiesta.

  • headers: informazioni sulla risposta ottenuta.

  • body: il contenuto vero e proprio della risposta.

    suggerimento

    la risposta ottenuta contiene la lista degli oggetti che corrispondono al filtro di ricerca applicato; ogni elemento della lista corrisponde alla struttura della risorsa principale definita in tutte le operazioni, sia di lettura che di inserimento/modifica, mentre gli elementi ad esso relazionati NON sono valorizzati.

Ricerca risorsa con paginazione e ordinamento​

Esiste la possibilità di ricerca “avanzata” specificando la paginazione e l’ordinamento nell’oggetto del body. Di seguito, il body per la ricerca di documenti da 6 a 10 (seconda pagina: la prima pagina corrisponde a PageNumber = 0), ordinati per numreg in ordine ascendente.

L’array orderingProperties specifica la lista delle coppie <NomeProprietàDTO, [ASC(0)|DESC(1)]> per l’ordinamento della search, mentre gli attributi pageNumber e pageSize specificano l’eventuale paginazione. Se la paginazione viene omessa, di default saranno restituiti i primi 50 elementi. Si rimanda al paragrafo successivo per la definizione dell’oggetto di ricerca.

Per eseguire una Search, occorre compiere una POST sulla risorsa “search".

Con riferimento alla chiamata:

{{webapi_base_url}}/rootPath/v1/{{scope}}/modulo/risorsa/Search?company={{defaultCompany}}&metadata=true&getTotalCount=true

La configurazione della richiesta HTTP come POST​

L’URL completo, composto nell’ordine da:

  • webapi_base_url: variabile in base alla configurazione del server
  • rootPath: “api”, NON variabile
  • versione: “v1”, NON variabile
  • scope: variabile in base a quale, tra gli ambienti precedentemente configurati, si desidera accedere
  • modulo: sigla, variabile in base all'appartenenza della risorsa interrogata
  • risorsa: sigla variabile in base al modulo
  • Search: “Search”, NON variabile

Il body della richiesta​

Il body della richiesta è obbligatorio e deve essere definito seguendo queste regole:

  • Deve contenere un oggetto filters con una singola proprietà items.
  • Un oggetto di tipo Item definisce le proprietà:
    • Comparer: operatore di confronto
    • Operator: operatore di comparazione tra gli elementi dell’array
    • PropertyName: nome della proprietà da filtrare
    • Value: valore della proprietà da filtrare

La proprietà PropertyName si riferisce alla struttura della risorsa principale definita in tutte le operazioni, sia di lettura che di inserimento/modifica; nel caso del documento quindi si può effettuare una ricerca filtrando tra le proprietà della testata del documento (numreg, numdoc, sezdoc, ecc…), ma non tra le righe del documento stesso.

La proprietà Comparer​

La proprietà Comparer è un enumerato di tipo integer, i cui valori possibili sono:

  • Equal: 0

  • NotEqual: 1

  • GreaterThan: 10

  • LessThan: 11

  • GreaterOrEqualThan: 12

  • LessOrEqualThan: 13

  • Contains: 20

  • NotContains: 21

  • StartsWith: 30

  • EndsWith: 40

    suggerimento

    0 - Equal - è il valore di default se la proprietà Comparer non viene specificata.

La proprietà Operator​

La proprietà Operator è un enumerato di tipo integer, i cui valori possibili sono:

  • None: 0

  • And: 1

  • Or: 2

  • Not: 3

    suggerimento

    0 - None - è il valore di default se la proprietà Operator non viene specificata; è obbligatorio specificare un valore diverso da 0 in caso di array di due o più elementi per gli elementi successivi al primo (si veda gli esempi seguenti).

Parametri di QueryString​

I parametri specificati in QueryString, sono:

  • defaultCompany: variabile in funzione dell'azienda di lavoro da utilizzare
  • metadata: “true”, variabile ed opzionale; utilizzato per recuperare i metadati della lookup insieme ai dati stessi
  • getTotalCount: “true”, variabile ed opzionale; utilizzato per valorizzare il campo totalCount nella response

Paginazione e Ordinamento​

  • Pagesize: Specifica la grandezza della pagina (di default è 50), impostando il parametro a -1 verranno restituiti tutti i record.
  • PageNumber: Specifica il numero di pagina da ritornare (la pagina iniziale è il numero 0).
  • OrderingProperties: Lista coppie <key, value> dove la chiave è il nome della proprietà del DTO su cui effettuare l’ordinamento e il valore la tipologia di ordinamento (ASC = 0, DESC = 1).

Codici risposta​

  • 200: la lista di oggetti di tipo {risorsa}DTO corrispondenti al risultato della search
  • 400: se il filtro della search non è stato specificato

VALIDAZIONE​

POST: webapi_base_url/v1/production/{modulo}/{risorsa}/validate

Parametri​

  • body: l'oggetto di tipo {risorsa}DTO da validare

Codici risposta​

  • 200: se l'oggetto specificato risulta VALIDO
  • 400: se l'oggetto da validare non è stato specificato
  • 409: se l'oggetto specificato risulta NON VALIDO: il contenuto della risposta contiene i messaggi di validazione prodotti

VALIDAZIONE PROPRIETA' DI UNA RISORSA​

POST: webapi_base_url/v1/production/{modulo}/{risorsa}/validateproperties

Parametri​

  • id: codice identificativo di un oggetto inesistente su cui validare le proprietà oppure per la validazione delle proprietà nei confronti di un nuovo oggetto
  • body: una o più coppie 'chiave=valore', in formato x-www-form-urlencoded, in cui la chiave è il nome della proprietà del DTO ed il valore da assegnare prima di eseguire la validazione stessa

Codici risposta​

  • 200: se le proprietà dell'oggetto specificate risultano VALIDE
  • 400: se le proprietà dell'oggetto da validare non sono state specificate
  • 409: se una o più proprietà dell'oggetto specificate risultano NON VALIDE: il contenuto della risposta contiene i messaggi di validazione prodotti

LOOKUP​

Per eseguire una lookup, occorre compiere una GET sulla risorsa “lookup".

Con riferimento alla chiamata:

{{webapi_base_url}}/rootPath/v1/{{scope}}/modulo/lookup/id?defaultcompany=000&metadata=true&_op=search

La configurazione della richiesta HTTP come GET​

L’URL completo, composto nell’ordine da:

  • webapi_base_url: variabile in base alla configurazione del server
  • rootPath: “api”, NON variabile
  • versione: “v1”, NON variabile
  • scope: variabile in base a quale, tra gli ambienti precedentemente configurati, si desidera accedere
  • modulo: sigla, variabile in base all'appartenenza della risorsa interrogata
  • risorsa: “lookup”, NON variabile
  • id: variabile che identifica la ricerca (lookup) da utilizzare (che può corrispondere al nome di un'entità oppure di un query descriptor)

Parametri di QueryString​

I parametri specificati in QueryString, sono:

  • user: variabile e opzionale, in funzione dell’utente applicativo da impersonare
  • defaultCompany: variabile in funzione della azienda di lavoro da utilizzare
  • metadata: “true”, variabile ed opzionale; utilizzato per recuperare i metadati della lookup insieme ai dati stessi
  • _op: da valorizzare obbligatoriamente a 'search' per attivare la funzionalità di ricerca

Filtri, Ordinamento e Paginazione​

I filtri, l'ordinamento e la paginazione sono passati nel Body della chiamata, in formato JSON così strutturato:

  • filters:
    • Comparer: operatore di confronto
    • Operator: operatore di comparazione tra gli elementi dell’array
    • PropertyName: nome dell'alias di colonna da filtrare (es. DocumentoTestataMG_Sezdoc)
    • Value: valore della proprietà da filtrare
  • orderingProperties: variabile ed opzionale; utilizzato per applicare un ordinamento (crescente o descrescente) su uno o più campi specificati nella lookup
  • pageNumber: variabile ed opzionale; utilizzato per specificare una specifica pagina di risultati della lookup chiamata (0 è la prima pagina, valore predefinito)
  • pageSize: variabile ed opzionale; utilizzato per definire la dimensione della pagina (50 è il valore predefinito)

Headers HTTP​

Gli headers HTTP configurati, la cui configurazione è stata descritta in precedenza.

La risposta ottenuta​

La risposta ottenuta, mostrata nell’immagine qui sopra, è composta da:

  • status: “200 OK”
  • headers: informazioni sulla risposta ottenuta
  • body: i dati della lookup ed opzionalmente i suoi metadati

E' possibile, inoltre, specificare in QueryString anche il parametro filter che permette di fare una ricerca "veloce" sui campi chiave e quei campi dichiarati come "descrittivi".

Elenco Lookup Disponibili​

GET: webapi_base_url/v1/production/FW/lookup/

Recupero Dati Lookup​

GET: /api/v1/production/{moduleAcron}/lookup/{lookupname}

POST: /api/v1/production/{moduleAcron}/lookup/{lookupname}

Parametri​

  • moduleAcron: sigla del modulo di appartenenza della lookup (esempio:CO,MG, ...)
  • lookupName: il nome della lookup relativa alle seguenti entità supportate
  • metadata: se true, recupera anche i metadati (la struttura) della lookup
  • _op: da valorizzare obbligatoriamente a 'search' per attivare la funzionalità di ricerca
  • body: il filtro di ricerca da applicare alla search, in formato JSON, con la seguente struttura:
    {
    "filters": {
      "items": [{
        "comparer": 0,
        "operator": 0,
        "propertyName": "ItemWH_SubFamilyWH_CodFamMg53",
        "value": "A"
      }]
    },
    "pageNumber": 0,
    "pagesize": 50,
    "orderingproperties": {
      "CustomerSupplierCO_Clifor": 0
    }
  }

Codici risposta​

  • 200: un array di oggetti, con la seguente struttura:
    {
    "description": "string",
    "lookupName": "string",
    "href": "string"
    }