Bendra informacija

Būsena	SUDERINTA
Portalas	iBiblioteka išorinis portalas
Sritis	R4
Etapas	El. knygų kūrimo komponentas
Atsakingas	Marius Valiuškis
Atsakingas derintojas	Unknown User (ieva.songailaite1)
Pateikta derinimui pirmą kartą	2021-02-01
Pateikta derinimui paskutinį kartą	2021-02-22
Turi būti suderinta iki	2021-03-04
Suderinta	2021-02-25

Turinys

Reikalavimai

Techninės specifikacijos reikalavimai

8.17. El. paslauga „El. knygų kūrimas“ turi būti teikiama kaip bendro naudojimo IT sprendimas, kuris turi leisti kitoms institucijoms norinčioms kurti el. knygas, konvertuoti failus į el. knygų formatus naudojant aplikacijų programavimo sąsają (angl. API – application programming interface).

Integracijos aprašymas

Ši knygų kūrimo paslauga skirta viešam naudojimui – interesuotoms institucijoms ar organizacijoms.

Paslauga sukurta užtikrinant elektroninės paslaugos „El. knygų kūrimas“ veikimą, kuriant elektronines knygas PDF arba EPUB3 formatais.

Naudojantis pateiktomis API sąsajomis galima sukurt ir gauti suformuotą dokumentą EPUB3 ar PDF formatais.

Techninę API dokumentaciją galite pasiekite nuoroda: https://metis.insoft.lt/metis-ebook-creator/swagger-ui.html#/

Dėl prisijungimų prie techninės API dokumentacijos prašome kreiptis į Lietuvos Nacionalinės Martyno Mažvydo bibliotekos atstovus šiuo el. pašto adresu: pagalba@lnb.lt

Elektroninės knygos inicijavimo metodas (POST metis-ebook-creator/publications)

Paskirtis	Inicijuoti elektroninės knygos kūrimo procesą EPUB3 ar PDF formatais naudojantis pateiktomis API sąsajomis.
Operacija	POST metis-ebook-creator/publications
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutės body dalyje JSON formatu (Content-Type: application/json) paduodama esybė PublicationMetadata
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką ir suformuotą kuriamos knygos unikalų identifikatorių id.

Esybė „Kuriamo leidinio metaduomenys“ (publicationMetadata)

publicationMetadata struktūros laukų sąrašas:

Pavadinimas	Tipas	Privalomas	Pasikartojantis	Aprašymas
author	String	Ne	Ne	Kuriamos elektroninės knygos autorius
description	String	Ne	Ne	Kuriamos elektroninės knygos trumpas aprašymas arba santrauka
digitalContentLabeling	String	Ne	Ne	Kuriamos elektroninės knygos licencijavimas
headline	String	Ne	Ne	Kuriamos elektroninės knygos antraštė
otherOrganisers	String	Ne	Ne	Kuriamos elektroninės knygos kiti kūrėjai
publisherFullName	String	Ne	Ne	Kuriamos elektroninės knygos leidėjas
releaseDate	Date	Ne	Ne	Kuriamos elektroninės knygos išleidimo data
subject	String	Ne	Ne	Kuriamos elektroninės knygos tematika

Elektroninės knygos aprašomosios dalies sukūrimo metodas (PUT metis-ebook-creator/publications/{id})

Paskirtis	Inicijuotos elektroninės knygos aprašomosios dalies perdavimas naudojantis API sąsaja
Operacija	PUT metis-ebook-creator/publications/{id}
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutės body dalyje JSON formatu (Content-Type: application/json) paduodama esybė PublicationMetadata kartu su parametru id gautu iš užklausos POST metis-ebook-creator/publications
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką.

Perduodamos užklausos JSON pavyzdys:

PublicationMetadata objekto pavyzdys

{
  "author": "string",
  "description": "string",
  "digitalContentLabeling": "string",
  "headline": "string",
  "otherOrganizers": "string",
  "publisherFullName": "string",
  "releaseDate": 2020,
  "subject": "string"
}

Elektroninės knygos priedų (attachments) įkėlimo metodas (POST metis-ebook-creator/files)

Paskirtis	Formuojamai elektroninei knygai įkelti prisegtukus naudojantis API sąsaja
Operacija	POST metis-ebook-creator/publications
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutės body dalyje JSON formatu (Content-Type: application/json) paduodama form-data tipo binarinė failų priėmimo reikšmė, Base64 formatu
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką su unikaliu įkelto failo uuid parametru.

Elektroninės knygos viršelio priskyrimo metodas (POST metis-ebook-creator/publications/{id}/cover/{file_uid})

Paskirtis	Priskirti formuojamai knygai įkeltą prisegtuką, kaip viršelį naudojantis API sąsaja
Operacija	POST metis-ebook-creator/publications
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutėje perduodant formuojamos knygos ir įkelto viršelio turinio nuorodų parametrus.
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką.

Viršelio priskyrimo užklausos parametrų aprašymas

Pavadinimas	Tipas	Privalomas	Pasikartojantis	Aprašymas
id	integer	Taip	Ne	Unikalus inicijuotos elektroninės knygos identifikatorius gautas sėkmingai įvykdžius metodą POST metis-ebook-creator/publications
uploadedFileUuid	string	Taip	Ne	Unikali įkelto binarinio rinkmenos turinio nuoroda į objektų saugyklą

Elektroninės knygos turinio pridėjimo metodas (POST metis-ebook-creator/publications/content-sections)

Paskirtis	Sukurti formuojamos elektroninės knygos turinio blokus naudojantis API sąsajomis
Operacija	POST metis-ebook-creator/publications
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutės body dalyje JSON formatu (Content-Type: application/json) paduodama esybė PublicationContentSection
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką ir suformuoto bloko unikalų identifikatorių - id.

Esybė „Elektroninės knygos turinio blokas“ (PublicationContentSection)

Pavadinimas	Tipas	Privalomas	Pasikartojantis	Aprašymas
content	String	Taip	Ne	Formuojamos elektroninės knygos įkeliamo bloko turinys tekstiniu arba struktūrizuotu HTML formatu.
contentOrderNo	integer	Taip	Ne	Įkelto bloko eilės numeris formuojamos elektroninės knygos blokų sąraše.
id	integer	Ne	Ne	Įkelto bloko grąžinamas kaip rezultatas ir naudojamas formuojant blokų struktūrą, kurios maksimalus gylis gali būti 3. Norint suformuoti kelių lygių struktūrą, žemesnio lygio blokas turi turėti nurodytą id reikšmę lauke parentId.
parentId	integer	Ne	Ne	Įkeliamo knygos turinio gilesnio bloko nuoroda į tėvinį bloką.
publicationId	integer	Taip	Ne	Inicijuotos knygos unikalus identifikatorius gautas sėkmingai įvykdžius metodą POST metis-ebook-creator/publications
title	String	Taip	Ne	Įkeliamo formuojamos elektroninės knygos bloko antraštė.

Elektroninės knygos turinio bloko struktūra

{
  "content": "string",
  "contentOrderNo": 0,
  "id": 0,
  "parentId": 0,
  "publicationId": 0,
  "title": "string"
}

Elektroninės knygos suformavimo pasirinktu formatu metodas (POST metis-ebook-creator/publications/{id}/export-{pdf arba epub})

Paskirtis	Gauti suformuotą elektroninę knygą norimu formatu.
Operacija	GET metis-ebook-creator/publications/{id}/export-{pdf arba epub}
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP GET žinutėje paduodama inicijuotos elektroninės knygos unikalus identifikatorius
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką ir suformuotą rinkmeną pdf arba epub formatu užkoduotą base64 algoritmu.

Elektroninės knygos suformavimo iš įkelto dokumento metodas (POST metis-ebook-creator/publications/from-file)

Paskirtis	Sukurti elektroninę knygą naudojantis pateiktomis API sąsajomis įkeliant docx formato rinkmeną.
Operacija	POST metis-ebook-creator/publications/from-file
Autentifikacija	Basic tipo autentifikacija užtikrinant stiprias slaptažodžio sudarymo taisykles.
Aprašymas	REST tipo sąsaja teikiama saugiu HTTPS protokolu.
	Operacijai HTTP POST žinutėje paduodama įkeliamos rinkmenos docx formatu turinys užpildant form-data tipo parametrą.
	Operacija sėkmės atveju grąžina HTTP 200 (OK) atsaką ir inicijuotos elektroninės knygos identifikatorių id.