Skip to content

API

Jump to bottom
Martin Řehánek edited this page Aug 31, 2020 · 13 revisions

Aplikační programové rozhraní

API systému slouží zejména k těmto dvěma základním účelům:

  1. Vkládání metadatových záznamů a zároveň rezervování urn:nbn identifikátoru pro publikaci popsanou tímto záznamem.
  2. Zobrazení záznamu digitálního dokumentu nebo přesměrování do konkrétní digitální knihovny na základě hodnotu urn:nbn (rezolvování).

Dále rozhraní umožňuje: 2. Zobrazení záznamů registrátorů, stavu každého urn:nbn, hodnoty registrar-scope identifikátoru vybraného typu. 2. Rezervaci balíku URN:NBN, zobrazení celkového počtu rezervovaných URN:NBN. 3. Pro konkrétní digitální dokument vkládání/editaci/odstranění registrar-scope identifikátorů. 4. Rezolvování na základě trojice * kódu registrátora, * typu registrar-scope identifikátoru, * hodnoty registrar-scope identifikátoru.

Jedná se o RESTful webové API. Pro autentizaci je použita metoda Basic access authentication. Operace, které jsou autorizované, jsou dostupné jen přes HTTPS, čímž je zabráněno zachycení loginu a hesla, které jinak metoda posílá v otevřené formě. Při pokusu o provedení operace přes HTTP bude vrácen kód 301 s přesměrováním na stejné URL, ale s prefixem https://. Je na administrátorovi, aby zpřístupnil alespoň tyto části aplikace přes HTTPS.

Verze API

Verze 1

Za první verzi API je považováno API předchozí implementace Resolveru, viz http://code.google.com/p/urnnbnresolver/. API obsahovalo jen rezolvování. Tato verze API není nadále podporována.

Verze 2

  • uri prefix /api/v2/
  • První verze aktuální implementace. Ukázky vstupních a výstupních dat jsou dostupné zde.
  • Tato verze API je stále funkční, je ale doporučeno přejít na V3 (v2 deprecated).
  • Vstupní data ve formátu API v2 jsou transformována na data ve formátu API v3 a poté volány operace API v3.
  • Odpovědi jsou ve formátu API v2.

Vstupní data musí být validní:

Podrobná specifikace API v2

Detailní popis operací a možných chybových stavů je dostupný v následujícím dokumentu na Google Docs: https://docs.google.com/spreadsheet/ccc?key=0Ag5aMq4LaXVcdGxGVUFITE1lVUk5blkyZ2ZIc3RuT1E

Verze 3

Oproti V2 došlo k následujícím změnám:

  • uri prefix /api/v3/
  • sjednocen formát výstupů všech operací. Ty jsou nově všechny validovatelné (http://resolver.nkp.cz/api/v3/response.xsd)
  • změna jmeného prostoru nejen výstupních xml, ale i vstupních. Namísto http://resolver.nkp.cz/v2/ nově http://resolver.nkp.cz/v3/.
  • změna url pro rezolvování podle registrar-scope identifikátoru (řetězec "id" nahrazen řetězcem "registrarScopeIdentifier")
  • změna url pro operace vložení/změnu hodnoty, zobrazení hodnoty, odstranění registrar-scope identifikátoru digitálního dokumentu a zobrazení, odstranění všech registrar-scope identifkátorů digitálního dokumentu (řetězec "identifiers" nahrazen řetězcem "registrarScopeIdentifiers")
  • sjednocení pořadí xml elementů s časovými známkami (created, modified, registered, deactivated) různých typů objektů v odpovědích API.
  • záznam digitální instance vždy obsahuje buď záznam digitální knihovny, nebo alespoň id digitální knihovny. Pro některé případy užití API tak jedna operace nahradí dvě i více operací. Např. zobrazení všech digitálních instancí digitálního dokumentu + zobrazení záznamu digitální instance (pro všechny instance) pro zjištění, jestli pro má digitální dokument instanci ve vybrané digitální knihovně (OAI Adapter).
  • registrace digitálního dokumentu
    • musí být validní podle http://resolver.nkp.cz/api/v3/digDocRegistration.xsd
    • operace se chová defenzivněji a preferuje realizaci operace před zamítnutím kvůli nedostatkům v datech. Konkrétně to znamená, že nevalidní obsahy elementů issn, isbn, ččnb nebudou použity, obsahy elementů přesahující určený limit budou zkráceny. V předchozí verzi by v obou případech došlo k zamítnutí operace z důvodu nevalidního vstupního dokumentu.
    • nově možné vložit urn:nbn předchůdce. Pokud operace proběhne úspěšně, předchůdce (urn:nbn) je deaktivován.
  • rozšířena množina povolených hodnot registrar-scope identifikátorů
    • v API v2: $ - _ . + ! * ' ( ) , : @
    • v API v3 všechny rezervované a nerezervované znaky podle RFC 3986 kromě znaku /. Jak typ, tak hodnota identifikátoru musí vždy začínat a končit písmenem nebo číslicí.
      • rezervované:
        • : ? # [ ] @ ! $ & ' ( ) * + , ; =
        • tyto znaky musí být url-encoded
      • nezervované:
        • číslice
        • písmena anglické abecedy (velké, malé)
        • následující znaky: - . _ ~
      • celkově nebyl žádný povolený znak zakázán, naopak přibyly tyto nově povolené znaky: ? [ ] ; & = #
  • import digitální instance
  • přidána operace deaktivace urn:nbn (bez předchůdců/následníků)

Podrobná specifikace API v3

Detailní popis operací a možných chybových stavů je dostupný v následujícím dokumentu na Google Docs: https://docs.google.com/spreadsheet/ccc?key=0Ag5aMq4LaXVcdFZ3MjBOb2s2UlZtb0ZqbV93WWJ4ZGc

Verze 4

Oproti V3 došlo k následujícím změnám:

Podrobná specifikace API v4

Detailní popis operací a možných chybových stavů je dostupný v následujícím dokumentu na Google Docs: https://docs.google.com/spreadsheets/d/1QT1dLjsjZrXzqdv-TqD18UTrCmzpQ24-ilv7-X1RbvY

Verze 5

Aktuálně preferovaný způsob importu dat představuje API v4. Oproti V4 došlo k následujícím změnám:

Podrobná specifikace API v5

Detailní popis operací a možných chybových stavů je dostupný v následujícím dokumentu na Google Docs: https://docs.google.com/spreadsheets/d/1JBWhkdek0AOT-uo3QC7GApkI6yP6GrvMLJkjAbVW1LM

Verze 6

Podrobná specifikace API v6

Detailní popis operací a možných chybových stavů je dostupný v následujícím dokumentu na Google Docs: https://docs.google.com/spreadsheets/d/1nh6GAAGCaVK7G-jW9LRjb0SaP1X-SRyR7EYjCk1Z6mY

Clone this wiki locally