1. Introduzione
Tamburino (http://www.tamburino.it) è la piattaforma online che raccoglie e distribuisce i dati di programmazione cinematografica, teatrale e televisiva a livello nazionale.
Tamburino Shop permette, previa registrazione, di acquistare le programmazioni di Tamburino. I dati acquistati saranno poi accessibili attraverso il sistema di content delivery, nei formati XML e JSON, effettuando apposite chiamate RESTful. Ogni utente è identificabile tramite una propria apikey che dovrà essere specificata ad ogni chiamata.
Questa guida intende documentare l’utente, che vuole accedere ai dati forniti da Tamburino Shop, quali passi eseguire per potersi registrare, acquistare e infine effettuare il download delle informazione che esso ha acquistato.
2. Il negozio
Tamburino Shop, accessibile tramite https://shop.tamburino.it, è un sito di e-commerce in cui è possibile acquistare prodotti digitali. Questi prodotti, come si accennava prima, saranno poi accessibili tramite servizi RESTful. Vedremo in apposito paragrafo come sarà poi possibile accedere a questi servizi.
2.1. L’acquisto
Come ogni sito di e-commerce, l’utente naviga all’interno del negozio virtuale e sceglie i prodotti a cui è interessato.
Per ogni prodotto dovrà indicare di quale periodo devono appartenere i dati del prodotto acquistato. Il periodo sarà specificato indicando la data di inizio e per quanto tempo si vuole i dati.
In alcuni casi altre caratteristiche del prodotto, come ad esempio la località, vengono richieste.
Una volta scelti i prodotti da acquistare, l’utente va nel carrello esegue la login oppure se non ha le credenziali effettua la registrazione. Dopodiché effettua il pagamento tramite PayPal oppure successivamente tramite bonifico bancario.
Solo una volta effettuato il pagamento l’utente avrà accesso ai dati che ha acquistato.
2.2. L’identificazione
Al momento della registrazione, che può avvenire sia contestualmente al primo acquisto che in maniera indipendente, l’utente viene registrato anche nel sistema di content delivery e gli viene assegnata una apikey che serve ad identificarlo in modo univoco.
Nella sua area personale di Tamburino Shop l’utente può vedere la propria apikey. Essa dovrà essere utilizzata quando si effettuano le chiamate per i servizi che ha acquistato.
2.3. I Servizi
Sempre nell’area personale di Tamburino Shop, all’utente viene visualizzato l’elenco dei servizi che esso ha acquistato.
Per ogni riga di questo elenco viene visualizzato il relativo prodotto acquistato, la data di inizio e la data di fine di disponibilità dei dati.
Inoltre compaiono la URL da richiamare e l’ID del Servizio.
Questo identificato è fondamentale per poter identificare il servizio vero e proprio al momento della richiesta dei dati.
In effetti ogni volta che si vuole richiamare un servizio si fa attraverso una URL che rappresenta il prodotto in questione. Questa URL viene completata con l’ID del Servizio.
2.4. Esempio
Se il prodotto acquistato è una programmazione cinematografica la URL da richiamare è nella forma
https://rest.tamburino.it/api/v1/movietheaters/programming/{ID del Servizio}
e ad esempio il relativo ID del Servizio è 456 e la apikey dell’utente è 1234567890abcdef, allora ad esempio la chiamata da effettuare, con i parametri in GET, sarà del tipo:
https://rest.tamburino.it/api/v1/movietheaters/programming/456?apikey=1234567890abcdef
In questo caso è stata richiesta la programmazione cinematografica in questione a partire dalla data di “domani” (default) per un (default) solo giorno. La risposta di questa chiamata è in formato XML (default).
Qualora l’utente non abbia accesso al servizio richiesto oppure non abbia accesso alle date scelte allora la chiamata ritornerà con un codice di errore HTTP.
3. Il content delivery
Una volta che l’utente ha effettuato l’acquisto dei prodotti desiderati può accedere ai relativi dati attraverso i servizi RESTful pubblicati dalla piattaforma di content delivery.
Il content delivery è accessibile tramite la URL base https://rest.tamburino.it/api/v1 e per ogni tipologia di servizio c’è un path specifico che deve essere concatenato alla URL base.
Cliccando qui potrai visionare la documentazione delle API in cui è specificato nel dettaglio l’elenco dei possibili servizi che è possibile richiamare.