Abstrakt ¶
W celu umożliwienia kontaktu między eKontaktem a innymi systemami Politechniki Gdańskiej (udostępnianymi przez wspólny system eUczelnia) stworzony został system interfejsów działających poprzez zapytania HTTP, które umożliwiają dostęp do części zasobów takich jak:
- dane osobowe pracowników oraz studentów,
- dane oraz struktura organizacyjna jednostek dydaktycznych oraz administracyjnych,
- prowadzone badania i wydawane publikacje wraz z powiązaniami z naukowcami i jednostkami, które są za nie odpowiedzialne,
- inne. System jest rozwijany i kolejne typy danych mogą być dostępne w przyszłości.
Wymiana danych z systemem eUczelnia odbywa się przez zapytania w postaci XML-RPC.
System udostępnia szereg funkcji, które mogą być wykonane:
- search - pozwala na wyszukanie elementów, oraz zwrócenie ich identyfikatorów do późniejszego wykorzystania,
- searchAndGet - działa tak jak search z tą różnicą, że zwraca pełne odwzorowanie obiektów,
- count - pozwala na policzenie ile obiektów spełnia zadane kryteria wyszukiwania,
- update - umożliwia zgłoszenie zmodyfikowania danych treści. Ze względu na wymogi bezpieczeństwa bardzo mała liczba obiektów jest modyfikowalna poprzez API. Aby zmiany w systemie się pojawiły zgłoszenie takie musi zostać zaakceptowane.
- insert - umożliwia zgłoszenie nowych danych. Podobnie jak w przypadku update dane te nie pojawią się od razu w systemie, lecz będą musiał zostać zaakceptowane.
- delete - zgłasza dany obiekt, jako obiekt usunięty. W analogii do update, zgłoszenie może zostać zaakceptowane, lub odrzucone.
- getElementsById - zwraca obiekty na podstawie przekazanych identyfikatorów
- getDistinctElementValues - zwraca wszystkie możliwe wartości danego pola. Ma zastosowanie dla wszystkich policzalnych pól typu referencja (takich jak wydział, jednostka, pracownik etc).
Wszystkie te metody wykorzystują szereg obiektów pomocniczych, które umożliwiają przekazanie szczegółowych danych dotyczących zapytania takich jak:
- fields - używany przy wszystkich metodach wyszukujących (tj. count, search, searchAndGet) obiekt zawierający nazwy pól oraz ich wartości, po których zostaną wyszukane obiekty
- sort_order - obiekt, który zawiera opis sposobu sortowania zwracanych informacji. Używany przy metodach wyszukujących, które zwracają obiekty (tj. search, searchAndGet).
- return_params - pozwala określić numer pierwszego zwracanego elementu oraz liczbę elementów, które powinny zostać zwrócone. Używany w celu ułatwienia zwracania fragmentów zapytania (np. przy paginacji)
- response - obiekt odpowiedzi systemu.
Rodzaj danych jakie zostaną zwrócone definiujemy poprzez wybranie w zapytaniu odpowiedniego modelu danych. Modele odzwierciedlają istniejące obiekty w systemie eUczelnia:
- user - Użytkownik
- employee - Pracownik
- student - Student
- publication - Publikacje
- research - Badania
- conference - Konferencje
- unit - Wydział / katedra / jednostka
- course - Przedmiot / karta przedmiotu
- course_grid - Siatka przedmiotów
- field - Kierunek studiów
- profile - Specjalność (profil dyplomowania)
- employer - Pracodawcy
- job - Oferty pracy
Aby nie przeciążać bazy danych, wszystkie pola, które wymagają skomplikowanych zapytań bazodanowych zostały oznaczone jako reference. Domyślnie atrybuty typu reference nie będą występować w zwracanych obiektach. Aby atrybut typu reference był zwrócony poprzez API, musi zostać to zaznaczone w zapytaniu. Przykłady wykorzystania tego mechanizmu można znaleźć w przypadkach użycia na końcu tego opisu. Wyjaśnienie oznaczeń przy opisywaniu obiektów i modeli:
int | liczba całkowita |
float | liczba zmiennoprzecinkowa (możliwe, że będzie to również liczba stałoprzecinkowa w przyszłości) |
string | łańcuch znaków, sformatowany zgodnie ze standardem HTML o długości nie przekraczającej 250 znaków |
text | łańcuch znaków, sformatowany zgodnie ze standardem HTML o dowolnej długości |
boolean | wartość true/false |
reference | w zależności od sposoby pobierania modelu: tablica identyfikatorów lub obiektów powiązanych. Domyślnie obiekty typu reference nie są zwracane przez system. |
date | data w formacie iso |
? | typ danej lub nazwa nie zostały jeszcze ustalone |