Tech4Art API2

Pagina di introduzione alle API di Tech4Art.

Versione con prefisso API2

La versione corrente è 0.23.1. Il prefisso delle chiamate alle funzioni di gestione del catalogo è:

    https://host/api2/v0.23.1/

La pagina swagger è disponibile a questo link.

Principali novità di questa versione

API2 contiene molte novità rispetto alla versione precedente. I principali ambiti sono:

Gestione dei profili utente.
Gestione dei media associati a catalog-element.

Gestione dei profili utente.

Attenzione! Dal momento che i profili utente sono condivisi tra più applicazioni, e non dipendono dalle versioni delle API del catalogo, le chiamate non contengono il prefisso con la versione API.

Profilo pubblico

    curl -X GET http://.../user-profiles/

    { ... [ ... {"username":"alice", "signature":"Prof. Alice", "preferred_language":"it", "image_url":"http://.../default-avatar.png"} ... ] ... }

    curl -X GET http://.../user-profiles/alice/

    {"username":"alice", "signature":"Prof. Alice", "preferred_language":"it", "image_url":"http://.../default-avatar.png"}

Note

La prima forma restituisce una lista, la seconda i dati di un singolo profilo identificato dallo username.
La chiamata non richiede autenticazione. L'unico metodo ammesso è GET (read-only).
Vengono restituti i dati del profilo pubblico. Il campo "signature" è per gli autori di testi che vogliano inserire il proprio nome completo, titolo o ruolo.
Se l'utente non ha inserito un'immagine viene assegnata un'immagine di default.

Profilo privato

Il profilo privato può essere utilizzato tra utenti di cui si conosce l'identità (per esempio catalogatori per una stessa istituzione). Al momento l'unico a vedere il profilo privato è l'utente stesso. L'endpoint per la modifica del profilo privato dovrebbe essere usato solo per preferred_language, signature, image.

    curl -X GET -H "Authorization: Bearer ..." http://host/owner-profile/

    {
        "user_type":"CA",
        "username":"alice",
        "first_name":"Alice",
        "last_name":"",
        "email":"alice@uno.it",
        "preferred_language":"it",
        "signature":"Prof. Alice",
        "affiliations":"Fondazione Uno",
        "image":null,
        "image_url":"http://.../default-avatar.png"
    }

Notare

owner-profile

al singolare. La chiamata richiede autenticazione. Viene restituito il profilo dell'utente autenticato.

Il campo user_type indica il tipo di utente. La codifica è da definire, ma CM sta per Community Member (non produce contenuti ma solo like) e CA per Catalogatore. Questo viene definito all'atto della registrazione e non è modificabile dall'utente, come pure il campo affiliations. Allo stato attuale è possibile modificare questi campi ma in una prossima versione saranno aggiunti controlli in modo da permettere cambiamenti solo previa approvazione di un responsabile.

    curl -X PATCH -H "Authorization: Bearer ..." 
        -H "Content-type: application/json" 
        --data '{"signature":"Professoressa Alice"}' http://.../owner-profile/

Per l'upload di un'immagine si utilizza il campo image. In assenza di image viene assegnato un image_url di default.

    curl -X PATCH -H "Authorization: Bearer ..." 
        -F signature="Professoressa Alice" 
        -F image=@assets/my-picture.jpg http://.../owner-profile/

    {
        ...
        "image":"http://.../my-picture.jpg",
        "image_url":"http://.../my-picture.png"
        ...
    }

Note:

Nel caso di file upload il content-type da utilizzare (qui implicito) non è più application/json ma multipart/form-data.
Con l'inserimento di un'immagine viene aggiornato anche il campo image_url. A parte l'operazione di upload, fare sempre riferimento a image_url, perché l'immagine caricata potrebbe subire delle modifiche (per esempio essere ridimensionata).
Ripetendo PATCH con un'immagine, anche la stessa, sul file system di destinazione verranno create più copie dello stesso file, con nomi diversi assegnati dal sistema. Non è previsto che l'utente possa cancellare l'immagine caricata, può solo sostituirla con un'altra.

Il profilo viene creato automaticamente al momento della creazione dell'account.

I metodi PUT e DELETE non sono supportati.

Elementi multimediali associati a catalog-element

Gli elementi multimediali sono costituiti da:

QR Code
Foto: DO_FT
Disegni: DO_DR
Video: DO_VD

Il QR code viene generato automaticamente al momento della creazione del catalog-element. Esiste un solo QR code per ciascun elemento. In futuro potranno esistere QR code associati ad altri tipi di oggetto (per esempio luoghi). Il contenuto del QR code è una stringa in formato JSON, della forma

        {
            "entity":"catalog-element",
            "id":"abcde-12345-xyz" 
        }

Spetta all'app di tradurre questa informazione in una azione (in questo caso aprire la scheda dell'elemento).

Un catalog-element può avere associati più contenuti di tipo foto, disegno o video. Ciascun contenuto va inserito nel sistema assieme alla scheda che lo descrive. Per esempio:

        curl -X "Authorization: Bearer ..." -X POST http://.../api2/0.23.1/catalog-photos/ 
            -F DO_FTAT="Didascalia foto" 
            -F element="abcde-12345-xyz" 
            -F media_content=@path-to-photo.jpg

Note:

L'operazione richiede autorizzazione (token).
Occorre indicare l'id del catalog-element associato.
Il content-type (qui implicito) è multipart/form-data e non application/json.
Il campo media_content va usato per l'operazione di upload. Successivamente, per referenziare il contenuto, occorre utilizzare il campo che contiene l'URL (in questo caso DO_FTAW).
Ripetendo l'operazione con metodo POST saranno associati più contenuti allo stesso catalog-element. Il metodo PATCH permette di cambiare le informazioni che descrivono il contenuto, ma se si include una immagine (anche identica alla precedente) questa sarà trattata come un nuovo file, aggiunto al file system. Il vecchio file non sarà più referenziato (ma potrebbe essere referenziato da altre applicazioni). Il metodo DELETE elimina le informazioni ma non il file.

Nuovi endpoint

I nuovi endpoint supportano i metodi GET, POST e PATCH.

    /api2/0.23.1/catalog-documents/     Documenti (per es. PDF) con informazioni aggiuntive.
    /api2/0.23.1/catalog-drawings/      Documentazione grafica.
    /api2/0.23.1/catalog-photos/        Documentazione fotografica.    
    /api2/0.23.1/catalog-videos/        Documentazione video.

Il metodo GET può ritornare una lista oppure un singolo contenuto. Per esempio:

    /api2/0.23.1/catalog-photos/             (lista)
    /api2/0.23.1/catalog-photos/photo-id/    (singolo)

Infine, un nuovo endpoint ritorna tutti i contenuti multimediali associati a un elemento.

    /api2/0.23.1/element-media/abcde-12345-xyz/

L'id da fornire è quello del catalog-element. Il risultato è un oggetto contenente tre array: photos, drawings, videos.

Cambiamenti nell'API catalog-elements

Le novità descritte sopra hanno comportato alcune modifiche all'endpoint catalog-elements. In particolare:

I campi relativi alla documentazione multimediale (DO_) non sono più presenti. I dati possono essere ottenuti tramite l'endpoint element-media.
Sono stati aggiunti tre campi aggregati: number_of_drawings, number_of_photos, number_of_videos. Questi campi riflettono il numero di contenuti multimediali dei tre tipi.

Ulteriori avvertenze

Allo stato attuale i controlli sui file caricati sono minimi. In futuro saranno aggiunti controlli per evitare problemi di sicurezza o di sovraccarico delle risorse.

Cambiamenti nelle versioni precedenti

CatalogReaction contiene il campo creator_username

creator_username può essere usato come criterio di filtro (query param: username).

    curl -X GET https://<host>/api/v0.23.1/catalog-reactions/?username=<nome_utente>

In luogo di un particolare username si può usare 'self' per l'utente autenticato:

    curl -X GET https://<host>/api/v0.23.1/catalog-reactions/?username=self

Nuovo endpoint per la lista dei preferiti

    curl -X GET https://<host>/api/v0.23.1/catalog-favorites/

ritorna la lista delle catalog-reaction dell'utente corrente (identificato dal token di autorizzazione) e le informazioni sul catalog-element associato. Per esempio, la risposta a una GET potrà avere la forma:

    {
        "count":10, <-- numero di reaction create dall'utente corrente
        "next":null,
        "previous":null,
        "results":[ <-- array
            { 
                "id":"837ba692-e499-4b7a-8086-fdac706023c7", <-- id della reaction
                "element": 
                {
                    "id":"47bcb6da-60bb-4317-823b-c20e7ed3936e", <-- id dell'element
                    ... <-- altri campi dell'element
                    "creator_username":"alice",
                    "is_public":true,
                    ... 
                },
                ... <- altri campi della reaction
                "creator_username":"bruno", <-- corrisponde all'utente corrente
            },
            ... <-- altri risultati
        ]
    }

Questo nuovo endpoint è stato creato per motivi di performance. Dal momento che la lista delle catalog-reactions di un utente ritorna anche l'id del corrispondente catalog-element, le altre informazioni sull'elemento possono essere ottenute utilizzando l'API /catalog-elements/id_elemento/, per ciascuno degli elementi. Il problema è che in questo modo si effettua una chiamata API per ciascun elemento, quindi aumentano gli accessi al database e il traffico di rete.

Entità

Le entità in questa versione sono le stesse delle precedenti:

cultural-objects
catalogs
catalog-elements
catalog-comments
catalog-reactions

Gestione degli utenti e dei permessi

Questa versione supporta autorizzazioni basate su token. Per ottenere un token occorre effettuare una richiesta POST contenente nel body i campi 'username' e 'password' con credenziali valide.

Esempio:

    curl -X POST -H "Content-Type: application/json" -d '{"username":"alice", "password":"secret"}' https://host/token_auth

Se le credenziali inserite sono corrette la risposta sarà simile a questa:

    {"token":"ef48622ee4d5e27a1ff918afbb602ca8a30ce10d"}

Da questo momento il si potrà usare il token per tutte le operazioni che richiedono autorizzazione. Il token non è (almeno per il momento) soggetto a scadenza.

Esempio:

    curl -X GET https://host/api/v0.23.1/cultural-institutions/

non ha bisogno di autorizzazione, ma

    curl -X POST -H "Content-Type: application/json" \
        -d '{"name": "test institution"}' \
        https://host/api/v0.23.1/cultural-institutions/'

richiede che l'utente sia autenticato. Il token deve essere passato come header come nell'esempio che segue:

    curl -X POST -H "Content-Type: application/json" \
        -H "Authorization: Bearer ef48622ee4d5e27a1ff918afbb602ca8a30ce10d" \
        -d '{"name": "test institution"}' \
        https://host/api/v0.21.1/cultural-institutions/'

Allo stesso modo, le richieste DELETE PATCH e PUT richiedono l'invio del token.

Elementi privati

Al momento della creazione un catalog-element è privato, visibile solo all'utente che l'ha creato. L'id dell'utente che ha creato l'elemento è inserito dal sistema, in base al token. Per rendere pubblico l'elemento si deve cambiare il valore del campo is_public, da False a True. Si possono usare i metodi PUT e PATCH.

Query parameters relativi a elementi privati.

    GET .../catalog-elements/  -- caso base: ritorna gli elementi pubblici di tutti gli utenti.


    GET .../catalog-elements/?username=user_name -- ritorna gli elementi pubblici dell'utente user_name 
    (non è mai possibile ottenere gli elementi privati di un utente diverso da quello autenticato).
    GET .../catalog-elements/?username=self -- ritorna gli elementi pubblici dell'utente autenticato.


    GET .../catalog-elements/?username=self&drafts=include -- ritorna gli elementi pubblici e privati dell'utente autenticato.
    GET .../catalog-elements/?username=self&drafts=only -- ritorna gli elementi privati dell'utente autenticato.


    GET .../catalog-elements/?drafts=include -- ritorna gli elementi pubblici di tutti gli utenti e quelli privati 
    dell'utente autenticato.
    GET .../catalog-elements/?drafts=only -- ritorna solo gli elementi privati dell'utente autenticato.

Parametri di filtro

I parametri di filtro restringono i risultati a quelli che soddisfano i criteri. Sono sempre opzionali.

    /cultural-institutions/?name=param_name
    /catalogs/?owner_institution=cultural_institution_id
    /catalog-elements/ in aggiunta ai già discussi username e drafts sono utilizzabili i seguenti parametri: 
      ?catalog=catalog_id
      ?CD_SSD
      ?CD_TSK
      ?CD_CDR
      ?LC_LCR
      ?LC_LCP
      ?LC_LCC
      ?LD_LDCN
    /catalog-comments/?element=catalog_element_id
    /catalog-comments/?username=self
    /catalog-comments/?username=some_user_name
    /catalog-reactions/?element=catalog_element_id
    /catalog-reactions/?username=self
    /catalog-reactions/?username=some_user_name