Um die Anbindung eigener Anwendungen an den URN-Service bzw. die URN-Rest-API zu unterstützen, bieten stellen wir einen Java-Client zur Verfügung.
Folgende Schnittstellen
UrnNamespaceRepository | Interface for using the query- and creation-methods related to URN-Namespaces. |
UrnOrganisationRepository | Interface for using the query-methods related to URN-Organisations. |
UrnPoliciesRepository | Interface for using the query-methods related to URN-Policies. |
UrnRepository | Interface for REST-API-Entry-Point to get information via RESTApiInfoResource about the URN-REST-API itself. |
UrnUrnRepository | Interface for using the query- and creation-methods related to URNs. |
wurden hier implementiert:
UrnNamespaceRestClient | Entry point for the users of the URN client to access the RESTNamespaceResources. |
UrnOrganisationRestClient | Entry point for the users of the URN client to access the RESTOrganisationResource. |
UrnPoliciesRestClient | Entry point for the users of the URN client to access the RESTPoliciesResource. |
UrnRestClient | Entry point for the users of the URN client to get information via RESTApiInfoResource about the URn-REST-API. |
UrnUrnRestClient | Handles the task of making the connections and the requests to the Urn-Service's RestApi. |
Schritt-für-Schritt-Anleitung
Technische Voraussetzungen:
- Die Verwendung von Java 8 oder kompatiblere JVM Sprache in der entsprechenden Version.
- Berechtigung zur Einspielung von URNS der eigenen Institutionen innerhalb des eigenen Namensraumes in Form von LOGIN / USER Credentials.
- Die URL zur URN-Rest-API (z.B.: "http://api.nbn-resolving.org/sandbox/v2/").
...
Implementierungen
Anker | ||||
---|---|---|---|---|
|
Codeblock | ||||
---|---|---|---|---|
| ||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/"; private static UrnRestClient urnRepository; public static void main(String[] args) { urnRepository = new UrnRestClient(V2_URI); final ApiInfo info = urnRepository.getInfo(); } |
...
Info | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
ApiInfo [ self=http://api.nbn-resolving.org/sandbox/v2/, ] |
...
Anker | ||||
---|---|---|---|---|
|
Um die Namensräume gezielt abfragen zu können, werden Filter- und Sortierparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
...
Suche über alle Namensräume
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/"; private static final String DEFAULT_NASP_WILDCARD = "urn:nbn:de*"; private static UrnNamespaceRestClient naspRepository; public static void main(String[] args) { naspRepository = new UrnNamespaceRestClient(V2_URI); final Optional<NamespaceFilter> naspFilter = Optional .of(new NamespaceFilter(NamespaceFilterKey.NAME, DEFAULT_NASP_WILDCARD)); final NamespaceSortParameters naspsortparams = new NamespaceSortParameters().getDefault(); naspsortparams.setSortBy(NamespaceSortKey.NAME); final PagingParameters pagingParameters = new PagingParameters().getDefault(); UrnRestResultNamespaceObject result = null; try { result = naspRepository.getNamespacesWithFilter(ORG_LOGIN, ORG_PASSWORD, naspFilter, naspsortparams, pagingParameters); } catch (final UrnRestApiNotAvailableException e) { System.out.println("The client cannot connect to the URN-REST-API."); } } |
...
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - You will only see information enabled for your login. .... .... .... |
...
Suche nach einem bestimmten Namensraum mittels Namen
Führt eine Suche nach einem bestimmten Namensraum durch.
...
Codeblock | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/"; private static final String DEFAULT_NASP_WILDCARD = "urn:nbn:de*"; private static final String ORG_NAMESPACE = "urn:nbn:de:0007"; private static UrnNamespaceRestClient naspRepository; public static void main(String[] args) { naspRepository = new UrnNamespaceRestClient(V2_URI); UrnRestResultNamespaceObject result = null; try { result = naspRepository.getNamespaceViaName(ORG_LOGIN, ORG_PASSWORD, ORG_NAMESPACE, ORG_USER); } catch (final UrnRestApiNotAvailableException e) { LOGGERSystem.out.errorprintln("The client cannot connect to the server. Is there an internet connection?"); URN-REST-API."); } LOGGER.info("Response End..."); } |
...
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getNamespace()... |
...
Anker |
---|
...
|
...
|
...
UrnOrganisationRestClient
Suche nach bestimmter Organisation mittels Login-Name
Führt eine Suche nach einer bestimmten Organisation durch.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Login-Name der zu suchenden Organisation. Der letzte Parameter ist nur für Admins relevant (runAs) und kann leer bleiben.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static UrnOrganisationRestClient orgRepository;
public static void main(String[] args) {
orgRepository = new UrnOrganisationRestClient(V2_URI);
UrnRestResultOrganisationObject resultObject = null;
try {
resultObject = orgRepository.getOrganisationByLogin(ORG_USER, ORG_PASSW, ORG_USER, ORG_USER);
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert der Einfachheit halber ein Ergebnisobjekt vom Typ UrnRestResultOrganisationObject zurück. Das eigentliche Ergebnis ist vom Typ RESTOrganisationRepresentation. Das UrnRestResultOrganisationObject "wrapt" das ursprüngliche RESTOrganisationRepresentationObjekt und fügt weitere Informationen hinzu (Anfrage erfolgreich, Statuscode).
Gut zu sehen, ist der Umstand, dass man als Nicht-Admin oder Nicht-Besitzer der Organisation nur eine eingeschränkte Sicht auf die Informationen hat (null-Werte).
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getOrganisationByID()... |
Suche nach bestimmter Organisation mittels Organisations-Identifier
Funktioniert analog zum vorherigen Beispiel.
Suche über alle Organisationen mittels Filter
Um die Organisationen gezielt abfragen zu können, werden Filter- und Sortierparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static UrnOrganisationRepository orgRepository;
public static void main(String[] args) {
orgRepository = new UrnOrganisationRestClient(V2_URI);
final Optional<OrganisationFilter> orgFilter = Optional
.of(new OrganisationFilter(OrganisationFilterKey.NAME, "Test*"));
UrnRestResultOrganisationObject resultObject = null;
try {
resultObject = orgRepository.getOrganisationsWithParams(ORG_LOGIN , ORG_PASSWORD , orgFilter,
new OrganisationSortParameters(), new PagingParameters());
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultOrganisationObject. Das UrnRestResultNamespaceObject "wrapt" die ursprünglichen RESTOrganisationRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...).Die Ergebnisse werden paginiert innerhalb einer ArrayList abgespeichert.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getOrganisationWithFilter()... [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - Response End... |
Anker | ||||
---|---|---|---|---|
|
Suche über alle URNs mittels Filter
Führt eine Suche nach URNs durch.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Identifier der zu suchenden Organisation. Der letzte Parameter ist nur für Admins relevant (runAs) und kann leer bleiben.
Um die URNs gezielter abfragen zu können, werden Filter-, Sortier-, und Paginierungsparameter benötigt.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String DEFAULT_URN_WILDCARD = "urn:nbn:de:01*";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
urnUrnRepository = new UrnUrnRestClient(V2_URI);
final Optional<UrnFilter> urnFilter = Optional.of(new UrnFilter(UrnFilterKey.URN, DEFAULT_URN_WILDCARD));
final UrnSortParameters urnsortparams = new UrnSortParameters().getDefault();
final PagingParameters pagingParameters = new PagingParameters().getDefault();
UrnRestResultUrnObject result = null;
try {
result = urnUrnRepository.getUrnsWithParams(ORG_LOGIN, ORG_PASSWORD, urnFilter, urnsortparams,
pagingParameters);
logUrnRestResultUrnObjectToString(result);
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultUrnObject. Das UrnRestResultUrnObject"wrapt" die ursprünglichen RESTUrnRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...).Die Ergebnisse werden paginiert innerhalb einer ArrayList abgespeichert.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getUrns()... [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - [main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - Response End... |
Lieferung von Vorschlägen für URN-Namen
Ein berechtigter Nutzer lässt sich URN-Namen für den eigenen Namensraum vorschlagen.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Name des betreffenden Namensraumes (ORG_NAMESPACE). Anzahl der Vorschläge (zw. 1 - 50).
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static UrnNamespaceRestClient naspRepository;
public static void main(String[] args) {
naspRepository = new UrnNamespaceRestClient(V2_URI);
UrnRestResultNamespaceObject suggestResult;
try {
suggestResult = naspRepository.suggestUrnName(ORG_USER, ORG_PASSW, ORG_NAMESPACE, "2");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultNamespaceObject. Das UrnRestResultNamespaceObject "wrapt" die ursprünglichen RESTNamespaceRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...). In diesem Fall ist nur die ArrayList mit den generierten URN-Namen relevant.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - getUrnSuggestions()... |
Hinzufügen einer neuen URN
Ein berechtigter Nutzer fügt dem URN-System eine neue URN samt URLs hinzu.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Identifier der zu suchenden Organisation. Der letzte Parameter ist nur für Admins relevant (runAs) und kann leer bleiben.
ORG_LOGIN und ORG_PASSWORD sind Platzhalter für das eigene LOGIN/PASSWORD.
Zusätzlich muss ein RESTCreateUrnRequest zusammengebaut werden, der wiederum einzelne RESTCreateUrlRequests beinhaltet.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
URI uriEins = null;
URI orgaId = null;
URI uriZwei = null;
String urnString = "urn:nbn:de:0007-2307251255492.453473381209";
try {
uriEins = new URI("https://test/forUrnClient_1.pdf");
uriZwei = new URI("https://test/fforUrnClient_2.docx");
orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID);
} catch (final URISyntaxException e) {
System.out.println("URI Syntax not conform to RFC.");
}
final List<de.dnb.resolvingdienste.urnadministration.urn.restapi.model.RESTCreateUrlRequest> requestsListUrls = new ArrayList<RESTCreateUrlRequest>();
UrnRestResultUrnObject response = null;
requestsListUrls.add(RESTCreateUrlRequestWithDefaultsBuilder.aRESTCreateUrlRequest().withOrganisation(orgaId)
.withUrl(uriEins).build());
requestsListUrls.add(RESTCreateUrlRequestWithDefaultsBuilder.aRESTCreateUrlRequest().withOrganisation(orgaId)
.withUrl(uriZwei).build());
final de.dnb.resolvingdienste.urnadministration.urn.restapi.model.RESTCreateUrnRequest createRequest = RESTCreateUrnRequestWithDefaultsBuilder
.aRESTCreateUrnRequest()
.withUrn(urnString).withUrls(requestsListUrls).build();
try {
response = urnUrnRepository.addNewUrn(ORG_USER, ORG_PASSW, createRequest, ORG_USER);
} catch (final UrnRestApiNotAvailableException e1) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultUrnObject. Das UrnRestResultUrnObject "wrapt" die ursprünglichen RESTUrnRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...). Die Ergebnisse werden paginiert innerhalb einer ArrayList abgespeichert. Das wird in unserem Fall größtenteils nicht benötigt.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - addUrn()... |
Hinzufügen einer neuen URL zu bestehender URN
Ein berechtigter Nutzer fügt einer URN eine neue URL hinzu.
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Name der URN und der RESTCreateUrlRequest. Der letzte Parameter (runAs) ist nur für Admins relevant und kann leer bleiben.
Zusätzlich muss ein RESTCreateUrlRequests zusammengebaut werden.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static final String URN_NAME = "urn:nbn:de:0007-2307251300155.775903492814";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
URI urineu = null;
URI orgaId = null;
try {
urineu = new URI("https://testUri/forClient_3".pdf");
orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID);
} catch (final URISyntaxException e) {
System.out.println("URI Syntax not conform to RFC.");
}
final RESTCreateUrlRequest createUrlRequest = new RESTCreateUrlRequest();
createUrlRequest.setUrl(urineu);
createUrlRequest.setOwner(orgaId);
UrnRestResultUrlObject restCallresponse = null;
try {
restCallresponse = urnUrnRepository.addNewUrl(ORG_USER, ORG_PASSW, URN_NAME , createUrlRequest, "");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultUrnObject. Das UrnRestResultUrnObject "wrapt" die ursprünglichen RESTUrlRepresentation-Objekte und fügt weitere wichtige Informationen hinzu (Anfrage erfolgreich, Anzahl Treffer, weitere Trefferseiten verfügbar, ...). In diesem besonderen Fall wird lediglich das RESTUrlRepresentation-Objekt in das UrnRestResultUrnObject gehängt und man bekommt die Info, ob der Request erfolgreich war.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - UrnRestResultUrlObject [ |
Updates aller URLs einer URN
Ein berechtigter Nutzer tauscht die eigenen URLs einer bestimmten URN aus.
urnUrnRepository.updateUrl(ORG_LOGIN, ORG_PASSWORD, URN_NAME , allMyUrls, "");
Notwendige Parameter sind wieder ORG_LOGIN, ORG_PASSWORD, Name der URN und der RESTCreateUrlRequest (allMyUrls). Der letzte Parameter (runAs) ist nur für Admins relevant und kann leer bleiben.
Der RESTCreateUrlRequests muss selbst zusammengebaut werden.
WICHTIG: Alle eigenen URLs, die vor diesem Request zur URN gehört haben und NICHT mehr in diesem Request aufgeführt werden, werden gelöscht. Das gilt nicht für fremde URLs anderer Institutionen.
Codeblock | ||||||
---|---|---|---|---|---|---|
| ||||||
private static final String V2_URI = "http://api.nbn-resolving.org/sandbox/v2/";
private static final String ORG_ID = "19066";
private static final String URN_NAME = "urn:nbn:de:0007-2307251300155.775903492814";
private static UrnUrnRestClient urnUrnRepository;
public static void main(String[] args) {
URI uriEins = null;
URI orgaId = null;
URI uriZwei = null;
try {
uriEins = new URI("https://testUri/forClient/repl_1".pdf");
uriZwei = new URI("https://testUri/forClient/repl_2".docx");
orgaId = new URI(V2_URI + "organisations/id/" + ORG_ID);
} catch (final URISyntaxException e) {
System.out.println("URI Syntax not conform to RFC.");
}
final List<RESTReplaceUrlRequest> allMyUrls = new ArrayList<RESTReplaceUrlRequest>();
final RESTReplaceUrlRequest eins = new RESTReplaceUrlRequest();
eins.setUrl(uriZwei);
eins.setPriority(1);
final RESTReplaceUrlRequest zwei = new RESTReplaceUrlRequest();
zwei.setUrl(uriDrei);
zwei.setPriority(0);
allMyUrls.add(eins);
allMyUrls.add(zwei);
UrnRestResultObject restCallresponse = null;
try {
restCallresponse = urnUrnRepository.updateUrl(ORG_LOGIN, ORG_PASSWORD, URN_NAME , allMyUrls,
"");
} catch (final UrnRestApiNotAvailableException e) {
System.out.println("The client cannot connect to the URN-REST-API.");
}
} |
Diese Anfrage liefert ein Ergebnisobjekt vom Typ UrnRestResultObject. In diesem besonderen Fall werden lediglich Information darüber zurückgegeben, ob der Request erfolgreich war.
Info | ||
---|---|---|
| ||
[main] INFO de.dnb.resolvingdienste.urn.restapi.client.testurnclient.mainForTest - You will only see information enabled for your login. | ||
Seiteneigenschaften | ||
| ||
Verwandte Vorgänge |