Specyfikacja dla serwera usług API

Struktury pakietów JSON

Podstawowy pakiet Request

{
    "auth": [1,"<app-id>","<secret-key>","<cat-id@domain>"],
	"lang": "<lang-code>",
	"exec": [
		["<komenda>",[<args>],{<kwargs>}],
		["<komenda>",[<args>],{<kwargs>}],
		...
	]
}

auth - zestaw danych autoryzujących: 1 (metoda autoryzacji), identyfikator aplikacji, klucz dostępowy, identyfikator katalogu bibliotecznego (uwaga: jeśli zestaw danych autoryzujących ma być inny, należy uzgodnić identyfikator metody autoryzacji)

lang - język, w jakim spodziewana jest odpowiedź. Jest to opcjonalny atrybut pakietu Request, domyślna wartość to pl_PL. Dostępne języki zwraca komenda APIInfo (zob. dalej).

exec - Lista komend wraz z opcjonalnymi parametrami, które mają zostać wykonane. Jeśli komenda przyjmuje argumenty pozycyjne - wówczas posiada listę tych parametrów w [<args>], natomiast jeśli posługuje się dodatkowo argumentami nazwanymi - przekazuje je w obiekcie {<kwargs>}. W szczególności argumenty pozycyjne - jeśli określone dla komendy - są obowiązkowe, natomiast argumenty nazwane są zawsze opcjonalne.

Poniższy, przykładowy pakiet, zawiera wszystkie dopuszczalne kombinacje wywołań komend.

{
	"auth": [1, "urn:uuid:19e5f51e-d34e-11e2-b3df-b8ac6fa3be47","Iug29KBkj2kpa2daIHRkm1nj","40020@lic867.sowa"],
	"exec": [
		["Command1",["Hello"],{"name": "Brian", "origin": "Nazareth", "age": 33}],
		["Command2",[1024, 768, 24]],
		["Command3",{"login": "brian00"}],
		["Command4"]
	]
}

W dokumentacji poszczególnych komend jako przykład będzie podawana struktura dla pojedynczej komendy (bez pozostałych elementów pakietu Request)

Podstawowy pakiet Response

Odpowiedź zawsze jest listą zawierającą dokładnie tyle elementów ile komend zostało przesłanych w pakiecie Request i każdy element tej listy jest rezultatem wykonania komendy zgodnie z jej pozycją w pakiecie Request. Rezultat jest obiektem JSON zawierającym co najmniej status wykonania komendy. W przypadku błędu dodatkowo zwracany jest message, zawierający komunikat dla użytkownika. Jeśli komenda zwraca dane (status 200), wówczas rezultat zawiera klucz data o strukturze zależnej od komendy.

[
	{
    	"status": 200,
		"message": "<optional-error-messsage>",
		"data": <command-specific>
	},
	...
]

status - status wykonania komendy. Może on przyjąć wartości:
200 - komenda zakończona sukcesem, odpowiedź dostępna w data
204 - komenda zakończona sukcesem, ale nie zwraca żadnej odpowiedzi
400 - błąd: niepoprawne wywołanie komendy (niepoprawne argumenty lub brak wymaganych argumentów)
401 - błąd: niepoprawne dane autoryzujące klienta API
402 - błąd: dostęp klienta do API został zablokowany
403 - błąd: brak uprawnień do wykonania operacji lub parametry komendy wskazują na obiekty, do których klient nie ma uprawnień
404 - błąd: parametry komendy wskazują na obiekty, które nie istnieją
405 - błąd: komenda nie istnieje
409 - błąd: konflikt (znaczenie zależy od komendy zwracającej ten status)
500 - błąd: wewnętrzny błąd aplikacji

message - w przypadku błędu zawiera tekstowy komunikat dla użytkownika.

data - dowolna struktura, wypełniana w przypadku odpowiedzi o statusie 200.

W dokumentacji poszczególnych komend jako przykład odpowiedzi będzie podawana wyłącznie struktura z pola data.

Komendy informacyjne

Pobranie informacji o API

Zwraca podstawowe informacje o API oraz dostępnych komendach.

[
	"APIInfo"
]

Odpowiedź przesyłana jest jako obiekt JSON. Klucze w obiekcie są następujące:

{
	"name": "SOWA2/MARC21",
	"version": "3.0",
	"validto": "2014-06-01T00:00:00Z",
	"languages": ["pl_PL", "en_GB"],
	"commands": ["APIInfo","CatalogueInfo","BookingRequest"]
} 

Pobranie informacji o katalogu bibliotecznym

Za pomocą tej komendy portal może pobrać podstawowe informacje o katalogu i dostępnych w nim usługach dodatkowych:

[
	"CatalogueInfo"
]

Odpowiedź przesyłana jest jako obiekt JSON. Klucze w obiekcie są następujące:

{
	"name": "Katalog księgozbioru",
	"url": "http://biblioteka-mbp.sowwwa.pl/sowacgi.php?KatID=5",
	"circulation": true,
	"authentication": true,
	"registration": false,
	"booking": true,
	"links": {
		"record": "http://biblioteka-mbp.sowwwa.pl/sowacgi.php?KatID=5&typ=record&id={{ rec_id }}",
        "login": "http://biblioteka-mbp.sowwwa.pl/sowacgi.php?KatID=5&typ=acc&eauth={{ url }}"
    },
	"patron_mdb": "e60483a4-800f-4afa-927e-bef6d8b636e3"
}

Pobranie informacji o miejscach udostępniania zbiorów

Jeśli katalog biblioteczny obsługuje udostępnianie zbiorów, niniejszą komendą informuje jakie są miejsca udostępniania (tzw. agendy).

[
	"CirculationInfo"
]

Odpowiedź przesyłana jest jako tablica obiektów JSON zawierających informacje o miejscach udostępniania. Klucze w obiekcie są następujące:

[
	{
		"circ_id": "2",
		"name": "Filia nr 2",
		"lending": true,
		"booking": true
	},
	{
		"circ_id": "3",
		"name": "Filia nr 3",
		"lending": true,
		"booking": false
	},
	{
		"circ_id": "20",
		"name': "Czytelnia dla dorosłych",
		"lending": false,
		"booking": false
	}
]

Pobranie informacji o polach niezbędnych do rejestracji nowego konta czytelnika

Jeśli katalog biblioteczny obsługuje automatyczną rejestrację nowych kont, niniejszą komendą można pobrać listę pól, jakie użytkownik musi wypełnić podczas rejestracji.

[
	"RegistrationInfo"
]

Odpowiedź przesyłana jest jako tablica obiektów JSON zawierających informacje o polach przeznaczonych do procesu rejestracji.

[
	{"fld_id": "surname", "name": "Nazwisko", "required": true},
	{"fld_id": "firstname", "name": "Imię", "required": true},
	{"fld_id": "email", "name": "Adres poczty elektronicznej", "required": true},
	{"fld_id": "pesel", "name": "Numer PESEL", "required": true, "validation": "^\\d{11}$"},
	{"fld_id": "idcard", "name": "Seria i numer dowodu", "required": false},
	{"fld_id": "phone", "name": "Numer telefonu", "required": false}
]

Komendy zarządzające kontem czytelnika

Sprawdzenie czy istnieje konto czytelnika w OPAC

Zanim portal zacznie próbować sugerować połączenie, albo utworzenie konta czytelnika w OPAC, sprawdza czy jest w OPAC zarejestrowane konto czytelnika na wybrany adres e-mail.

[
	"AccountCheck",
	["michal@fmail.com"]
]

Jeśli konto czytelnika na dany adres email zostanie znalezione, zwracana jest prosta informacja w postaci obiektu JSON:

{
	"user_id": "O5",
	"label": "Michał",
	"remote_id": "szu"
}

W przypadku, gdy nie ma konta czytelnika dla danego adres e-mail, operacja zwróci status 404.

Powiązanie konta użytkownika portalu z istniejącym kontem czytelnika w OPAC

Użytkownik z poziomu portalu może powiązać swoje konto z kontem czytelnika w katalogu bibliotecznym. Operacja powiązania konta umożliwia portalowi wykonywanie dalszych operacji na koncie czytelnika bez konieczności każdorazowego wpisywania hasła. Wprowadzenie hasła do konta czytelnika konieczne jest tylko w momencie jednorazowej operacji powiązania kont w obu systemach.

[
	"AccountLink",
	["89102013813","m0iet@jn3#a$lO","michal@fmail.com","szu","33928575c9cd4f99945a5866bb501836"]
]

Odpowiedź w przypadku poprawnego powiązania kont to obiekt JSON o podanych kluczach:

{
	"user_id": "O5",
	"key": "19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318",
	"label": "Michał"
}

Skasowanie powiązania konta w portalu z kontem czytelnika w OPAC

Konto w portalu, powiązane z kontem w OPAC, może zostać odłączone po wykonaniu tej operacji. Opcjonalny parametr password pozwala na wykonanie operacji odlinkowania w przypadku, gdy z jakiegoś powodu zapamiętany klucz obcy jest nieprawidłowy.

[
	"AccountUnlink",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318"],
]

Poprawne wykonanie operacji zwróci status 204. W przypadku błędu klucza lub hasła - zwróci 403. W przypadku gdy dane konto nie jest powiązane - 404.

Utworzenie nowego konta czytelnika w OPAC

Użytkownik z poziomu portalu będzie mógł automatycznie utworzyć sobie konto czytelnika w OPAC o ile ten oferuje taką usługę (zob. CatalogueInfo) i automatycznie powiązać go z kontem portalu.

Do utworzenia konta w OPAC niezbędne jest podanie danych osobowych czytelnika. Zestaw pól dostępnych zwraca komenda RegistrationInfo. Użytkownik nie tworzy swojego hasła do konta czytelnika. System biblioteczny automatycznie nadaje losowe hasło i wysyła je użytkownikowi po skutecznej rejestracji na podany adres e-mail.

UWAGA: konto czytelnika w bibliotece może nie umożliwiać od razu wszystkich opcji (np. rezerwowania książek) do czasu potwierdzenia rejestracji przez bibliotekarza. Jest to zależne od regulaminu konkretnej biblioteki.

[
	"AccountCreate",
	[
		{
			"surname": "Testowski", 
			"firstname": "Michał",
			"email": "michal@fmail.com",
			"pesel": "89102013813"
		},
		"michal@fmail.com",
		"szu",
		"33928575c9cd4f99945a5866bb501836"
	],
	{ "avatar": "http://s.w.bibliotece.pl/static/gen/avatars/szu/m0.png" }
]

Może dziwić w przykładzie podwójne przekazanie adresu e-mail. Jest to konsekwencja zwrócenia przez komendę RegistrationInfo pola email jako obowiązkowego (tak było w przykładzie). Niezależnie od tego, że komenda AccountCreate wymaga podania emaila jako argumentu pozycyjnego. W praktyce RegistrationInfo nie powinno jednak wymagać adresu email (bo jest on i tak obowiązkowym polem przy AccountCreate).

Odpowiedź w przypadku poprawnego utworzenia i powiązania kont to obiekt JSON o podanych kluczach:

{
	"user_id": "O5",
	"key": "19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318",
	"label": "Michał"
}

Odpowiedź w przypadku błędu (np. podane dane podczas rejestracji wskazują na istniejące już wcześniej konto czytelnika) będzie generować status 409.

{
	"status": 409,
	"message": "Adres e-mail jest już przypisany do istniejącego konta czytelnika."
}

Zarezerwowanie książki przez użytkownika

Operacja próbuje zarezerwować dla użytkownika egzemplarz przypisany do danego rekordu. Opcjonalnie można podać identyfikator miejsca udostępniania (agendy) - wówczas pod uwagę będą brane tylko egzemplarze dostępne w wybranej agendzie.

Jeśli jest jakikolwiek dostępny egzemplarz, wówczas zostanie on dla czytelnika zarezerwowany. Jeśli wszystkie są aktualnie wypożyczone, czytelnik zostanie zapisany na listę oczekujących (chyba że atrybut nazwany nowait tego zabrania). Jeśli nie ma w ogóle udostępnionych egzemplarzy lub nie są one dostępne w wybranej agendzie, wówczas operacja się nie powiedzie.

[
	"BookingRequest",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318","U4551/0"],
	{"circ_id": "0"}
]

Odpowiedź w przypadku poprawnego wykonania operacji to obiekt JSON o następujących kluczach:

{
	"order": 2,
	"validto": "2013-06-30T23:59:59Z",
	"circ_id": "0"
}

Odpowiedź w przypadku braku udostępnionych egzemplarzy w ogóle (lub w żądanej agendzie) zwróci status 409 wraz ze stosownym komunikatem o braku dostępności.

Anulowanie rezerwacji przez użytkownika

Odwrotność komendy BookingRequest - anuluje wcześniej dokonaną rezerwację książki. Jeśli ten sam identyfikator rekordu książki dotyczy więcej niż jednej rezerwacji (np. czytelnik zarezerwował tą samą książkę w różnych miejscach), podanie identyfikatora miejsca udostępniania jest konieczne.

[
	"BookingCancel",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318","U4551/0"],
	{"circ_id": "0"}
]

Odpowiedź w przypadku poprawnego anulowania rezerwacji zwraca status 204. Jeśli anulowanie się nie powiedzie (np. rezerwacja została już potwierdzona do odbioru przez bibliotekarza), zwrócony zostanie status 409.

Przedłużenie ważności wypożyczenia lub zamówienia

W przypadku książki już wypożyczonej - polecenie pozwala na prolongatę terminu zwrotu. W przypadku gdy czytelnik dopiero oczekuje na książkę - pozwala przedłużyć termin ważności zamówienia (o ile jest taka konieczność - zob. AccountStatus).

Z uwagi na to, że w każdej bibliotece może funkcjonować inny regulamin dotyczący przedłużania tych terminów (od limitów na liczbę operacji, aż do całkowitego braku takiej możliwości włącznie) polecenie musi zwracać czytelny i jasny komunikat o powodach odmowy prolongaty.

[
	"BookingProlong",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318","U4551/0"],
	{"validto": "2013-07-30"}
]

Odpowiedź w przypadku poprawnego wykonania operacji to obiekt JSON o następujących kluczach:

{
	"validto": "2013-07-30"
}

Odpowiedź w przypadku braku możliwości wykonania prolongaty zwróci status 409 wraz ze stosownym komunikatem o przyczynie odmowy.

Pobranie aktualnego stanu konta czytelnika

Jako "stan aktualny" należy rozumieć listę rekordów, które czytelnik ma aktualnie wypożyczone lub je zarezerwował. Pobierana jest także ewentualna informacja o blokadzie konta czytelnika.

[
	"AccountStatus",
	['O5','19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318']
]

Odpowiedź jest obiektem JSON o następujących kluczach:

{
	"loaned": [
		{
			"rec_id": "U1",
			"ipub_id": "c5d721cbc3664fa4ab8938310415e056",
			"date": "2013-06-30",
			"validto": "2013-07-30",
			"circ_id": "0"
		}
	],
	"booked": [
		{
			"rec_id": "U2",
			"date": "2013-06-15T12:00:00Z",
			"validto": "2013-07-15",
			"circ_id": "20",
			"order": 1
		}
	],
	"blocked": "Nie zapłacono kary za przetrzymanie książek"
}

Pobranie historii wypożyczeń dla konta czytelnika

Zwracana jest historia wypożyczeń czytelnika - na życzenie tylko lista pozycji PO określonej dacie.

[
	"AccountHistory",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318"],
	{"after": "2013-01-01"}
]

Odpowiedź jest listą obiektów JSON o następujących kluczach:

[
	{
		"rec_id": "U1",
		"ipub_id": "c5d721cbc3664fa4ab8938310415e056",
		"date": "2013-01-01",
		"returned": "2013-06-01",
		"circ_id": "0"
	},
	...
]

Pobranie jednorazowego URL do konta czytelnika w OPAC

Polecenie służy do pobrania z systemu bibliotecznego jednorazowego adresu URL, który pozwala na otwarcie w przeglądarce katalogu OPAC już zalogowanego do konta czytelnika.

[
	"AccountURL",
	["O5","19_0a5fb4e968264b8f66a345a77bcc30de8520d9fb4a2cc26188d3d259d1008318"]
]

Odpowiedzią jest obiekt JSON: adres URL, dzięki któremu czytelnik może otworzyć swoje konto bez wpisywania hasła.

{
	"url": "http://biblioteka-mbp.sowwwa.pl/sowacgi.php?KatID=5&typ=acc&key=6624fa17c1b34aedb49e8dcdb40bcad0",
	"iframe": true
}