Interfejs programistyczny aplikacji
Otwarty system antyplagiatowy udostępnia dwa interfejsy komunikacji, jeden do wersji lokalnej instalowanej na komputerze uczelni, drugi do Nekst umożliwiający sprawdzanie prac w internecie (korzysta z niego wersja lokalna).
Obydwa interfejsy zostały wykonane w oparciu o REST (Representational State Transfer).
Spis treści
API OSA
Aktualna wersja została opracowana na potrzeby integracji z systemem USOS. Docelowo chcemy ją rozszerzyć by można było się zintegrować z dowolnym oprogramowaniem.
API v1
Wersja v1 została opracowana z myślą o USOS poniżej 6.1.2. Więcej na temat integracji z tym systemem tutaj: Konfiguracja APD
Tworzenie zadań i odbieranie raportów
POST: http://<adres serwera osa>/api/job/create (dla OSY ver. 3.4.4)
lub
POST: http://<adres_osy>/api/v1/usos/job (dla OSY ver. 3.5.0+ oraz ustawionym
parametrem -Dosa.usos-client.version=v1 w pliku setenv.sh)
Uwaga! POST wysyłamy w kodowaniu UTF-8
parametry (podkreślone są wymagane):
- reportURL - Adres do przesłania raportu (adres zwrotny)
- university - Nazwa uniwersytetu
- polonCode - Kod POL-on uniwersytetu (w tej chwili OSA nie zapisuje tych informacji)
- languageCode - Kod ISO języka pracy [możliwe pola: pl, en. Parametr tylko informacyjny - nie ma wpływu na wyniki]
- documentType - Typ pracy [możliwe pola: licenciate, engineer, master, postgraduate, doctoral]
- faculty - Jednostka podstawowa
- fieldOfStudy - Kierunek studiów (w tej chwili OSA nie zapisuje tych informacji)
- knowledgeArea - Obszar wiedzy
- title - Tytuł pracy
- author - Autor
- promoter - Promotor
- reviewer - Recenzent
- file - Plik
odpowiedź:
- status - Status zgłoszenia
- message - Tekstowy komunikat
- guid - Identyfikator zgłoszenia
Po wykonanej analizie antyplagiatowej system próbuje odesłać raport na wskazany adres (reportURL) przekazując następujące parametry:
- id - Identyfikator zgłoszenia (GUID)
- file - Plik z raportem
oczekując następujących parametrów:
- status - Status
- message - Komunikat
Mapowanie kodów obszarów:
- OB01 -> Obszar nauk humanistycznych
- OB02 -> Obszar nauk społecznych
- OB03 -> Obszar nauk ścisłych
- OB04 -> Obszar nauk przyrodniczych
- OB05 -> Obszar nauk technicznych
- OB06 -> Obszar nauk rolniczych, leśnych i weterynaryjnych
- OB07 -> Obszar nauk medycznych i nauk o zdrowiu oraz nauk o kulturze fizycznej
- OB08 -> Obszar sztuki
Przykładowe dane przesłane przez API:
title='Motywowanie pracowników -narzędzia motywowania', author='Jacecka, Mirosława', promoter='Kowalska, Ewa', reviewer='Marcinkiewicz, Maciej', authorID='Jacecka, Mirosława, 1335132', promoterID='Kowalska, Ewa, 1344837', reviewerID='Marcinkiewicz, Maciej, 1335138', university='Uniwersytet DEMO', polonCode='UW', faculty='Wydział Zarządzania', documentType='licenciate', languageCode='pl', knowledgeArea='OB02', reportURL='https://apd.demo.usos.edu.pl/diplomas/osa/report/', file=XXXXX
Uwaga dla uczelni używających ExternalID dla wiązania prac z konkretnymi kontami w OSA
Pola promoterID, authorID, reviewerID - zostały wynegocjowane z USOSem. OSA wykorzystuje tylko promoterID w celu powiązania pracy z kontem Użytkownika OSA w taki sposób, że praca również wyświetla się danemu promotorowi w Moje dokumenty. W takim przypadku format wpisu powinien być jak powyżej, tj:
promoterID='Nazwisko, Imię, ExternalID'
oraz ExternalID musi się zgadzać z tym uzupełnionym w Użytkownicy -> Edytuj -> Zewnętrzne ID
API v2
Wersja v2 została opracowana z myślą o USOS 6.1.2+. Więcej na temat integracji z tym systemem tutaj: Konfiguracja APD
Tworzenie zadań i odbieranie raportów
POST: http://<adres_osy>/api/v2/usos/job (wymagana OSA ver. 3.5.0+) - wymagany brak parametru na temat API w pliku setenv.sh lub ustawienie jego na -Dosa.usos-client.version=v2 Uwaga! POST wysyłamy w kodowaniu UTF-8
parametry (podkreślone są wymagane):
- action - Rodzaj zgłoszenia
- reportURL - Adres do przesłania raportu (adres zwrotny)
- metadata - Metadane pracy w formacie JSON
- file - Plik pracy
- guid - Identyfikator zgłoszenia (wymagane przy action="update")
odpowiedź:
- status - Status zgłoszenia
- message - Tekstowy komunikat
- guid - Identyfikator zgłoszenia
Odnośnie action:
new - standardowe zgłoszenie update - aktualizacja danych pracy o ID=guid i wysłanie ponownie aktualnego raportu PDF
Odnośnie metadata w formacie JSON:
{
"university":"Politechnika Warszawska",
"polonCode":"PW",
"title":"O obrotach sfer niebieskich",
"languageCode":"pl",
"documentTypes":[
"engineer",
"master"
],
"faculties":[
"Wydział Elektryczny",
"Wydział Fizyki"
],
"fieldsOfStudy":[
"Elekrotechnika",
"Fizyka chemiczna"
],
"knowledgeAreas":[
"OB01",
"OB05"
],
"authors":[
{
"firstName":"Mikołaj",
"lastName":"Kopernik",
"usosID":111223
},
{
"firstName":"Maria",
"lastName":"Skłodowska",
"usosID":111553
}
],
"promoters":[
{
"firstName":"Michał",
"lastName":"Jachaś",
"usosID":441553
},
{
"firstName":"Sebastian",
"lastName":"Bąk",
"usosID":441123
}
],
"reviewers":[
{
"firstName":"JJ",
"lastName":"Torpeda",
"usosID":422212
},
{
"firstName":"Domino",
"lastName":"Jachaś",
"usosID":453123
}
]
}
Jest to standard opracowany przez USOSa i dla OSY w niektórych miejscach jest nadmiarowy -> Uwagi do parametrów:
language - [pl, en, de, fr, it, ru, es, "" - jako inny] polonCode - jest ignorowany authors - OSA pobiera konkatenację wartości. USOS ID jest ignorowany promoters - OSA pobiera konkatenację wartości. usosId=externalId pobierany jest pierwszej osoby reviewers - OSA pobiera konkatenację wartości. USOS ID jest ignorowany faculties - OSA pobiera konkatenację wartości documentTypes - OSA pobiera pierwszą wartość. Parametry jak w v1 knowledgeAreas - OSA pobiera pierwszą wartość. Parametry jak w v1
FAQ
Po wysłaniu requestu metryka pracy nie posiada polskich liter
- Wątek na Redmine poruszający ten problem dla integracji z systemem DSpace
Zobacz też
