Istruzioni tecniche API NBN
L’utilizzo della API è aperto a tutti i repository delle istituzioni associate a Magazzini Digitali.
Prima di essere abilitati all’utilizzo della API deve essere inoltrata richiesta di abilitazione di un account di accesso al servizio NBN.
La documentazione di seguito è destinata ad a scopo tecnico e richiede una conoscenza di base di programmazione e del protocollo HTTP.
1. Note generali
Sicurezza
Le richieste al servizio possono essere eseguite solo a seguito di autenticazione mediante Authentication Digest.
Endpoint
L’API è implementata in RESTful style e l’end point utilizzato è:
http://nbn.depositolegale.it
Accesso al servizio:
La URI http://nbn.depositolegale.it/api/nbn_generator.pl accetta richiesta con metodo HTTP POST.
La URI http://nbn.depositolegale.it/{nbn}, dove {nbn} è un NBN, restituisce la risorsa.
Content Type
Per il metodo POST è richiesto un header addizionale, il quale specifichi la comunicazione di parametri in formato JSON
Content-Type:application/json; charset:UTF-8
Standard di generazione degli identificativi NBN
Gli identificatori NBN verranno generati, seguendo la specifica RFC 3188, con la seguente sinatssi:
URN:NBN:<ISO 3166 country code>:<sub-namespace code>-<assigned NBN string>
Dove <sub-namespace code> corrisponde al codice assegnato all’istituzione e <assigned NBN string> è un numero incrementale UNIVOCO completamente opaco rispetto alla risorsa a cui viene assegnato, alla data del suo deposito o al puntatore alla rappresentazione di tale risorsa sull’IR di origine.
2. Sicurezza
Tutte le richieste a questo sistema richiedono un header con HTTP Digest Authentication. Username e password di accesso saranno quelli forniti a seguito dell’adesione a Magazzini Digitali e della registrazione al servizio NBN.
L’utilizzo dell’account istituzionale comporta:
– L’autorizzazione a generare NBN solo con il sub-namespace code specificatamente assegnato
– La possibilità di generare giornalmente un numero di identificativi non limitato
3. NBN API GET
URI: http://nbn.depositolegale.it/{nbn} dove {nbn} è un NBN specifico.
La richiesta ritorna una URL con i dati riepilogativi relative allo specifico NBN e i link alle rappresentazioni delle risorse sull’IR e, se presenti su MD
Request headers
none
Request body
empty
Response headers
none
Response body
Se il response status è 200, la pagina di risposta conterrà i dati relativi all’NBN,
altrimenti verrà visualizzato un non-200 status con relativa breve spiegazione.
4. NBN API POST
URI: http://nbn.depositolegale.it/api/nbn_generator.pl
Il POST genererà un nuovo NBN, se la risorsa URL associate non è già presente all’interno del sistema come già associata ad un identificativo.
Request headers
Content-Type:application-json
Request body
– Parametri obbligatori:
action=nbn_create
url={url}
dove {url} deve essere sostituita con la URL puntatore alla rappresentazione della risorsa presente nel repository.
– Parametri opzionali:
metadataURL={metadataurl}
dove {metadataurl} deve essere sostituita con la URL puntatore ai metadati descrittivi della risorsa presenti nel repository.
Response headers
Content-Type:application-json
Response body
Se la richiesta è andata a buon fine, viene restituita una stringa JSON contenente breve spiegazione dello status code ( es. created, url already exists.. ) ed identificativo NBN (indicato nella tabella di seguito nel campo {nbn} ).
Nel caso in cui la richiesta avvenga per una nuova risorsa il response header status avrà valore “201 created”.
Response header status | Response JSON body parameters |
201 created | status = 201, nbn created nbn = {nbn} |
Nell’eventualità in cui la URL per la quale è stato richiesto l’identificativo sia già presente all’interno del Registro Centrale, verrà restituito l’NBN già associato.
Il response header status avrà valore “201 OK”.
Tale procedura è ottimizzata per gestire eventuali riallineamenti delle informazioni all’interno degli IR.
Response header status | Response JSON body parameters |
201 OK | status = 201, url aligned nbn = {nbn} |
Gestione dell’errore
Gli errori di risposta ai POST sono comunicati mediante response header statuses del protocollo HTTP.
Le informazioni addizionali riguardo alla tipologia dell’errore sono incluse nel body della return call, formattati in una stinga JSON. Di seguito i possibili errori e le cause associate.
Response header status | Response body | Errore |
400 Bad Request | status = 400 Bad request, wrong action. | Errore nel campo obbigatorio action del request body |
400 Bad Request | status = 400 Bad Request, not valid url | Il contenuto del campo obbligatorio url del request body non rispetta lo standard corretto di sintassi per le URL |
401 Unauthorized | status = 401 Unauthorized, wrong username | I parametri di autorizzazione non sono validi per l’accesso al sistema |
402 url alredy exists | status = 402 url alredy existsnbn = {nbn} | La risorsa per la quale si richiede NBN è già presente nel sistema. L’identificativo corrispondente è restituito nel corpo della risposta. |
500 Internal Server Error | status = 500 Internal Server Error, failed tansaction. | Transazione fallita, ritentare successivamente e, se il problema persiste, contattare l’amministratore. |