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”.

 

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.

 

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.