Wersja z 13:42, 4 lis 2016

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).

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

API Nekst

Serwis REST API znajduje się pod adresem: api.antyplagiat.nekst.pl.

Komunikacja odbywa się za pomocą protokołu HTTPS (GET i POST), zaś odpowiedzi zwrotne są mapowane na JSON’a lub XML’a w zależności od parametru nagłówka (HTTP header) Accept: application/json lub Accept: application/xhtml+xml.

Autoryzacja

W celu uzyskania dostępu do API należy pobrać token autoryzacyjny za pomocą poniższej metody:

GET: antyplagiat.nekst.pl/auth/getToken?login={login}

parametry:

• login - nazwa użytkownika dostarczona przez administratora.

Każdorazowe wykonanie jakiejkolwiek metody z API wymaga wcześniejszego pobrania nowego tokenu oraz parametru md5 obliczonego według wzoru:

$md5 = md5 ( md5 ( $apiKey ) + $tokenFromGetTokenMethod );

gdzie:

• md5() - funkcja skrótu MD5
• $md5 - parametr przekazywany przy dostępie do API
• $tokenFromGetTokenMethod - token uzyskany za pomocą metody “getToken”
• $apiKey - klucz dostępowy do API uzyskany od administratora

Jeśli chcemy sprawdzić naszą metodę wyliczenia parametru $md5 możemy skorzystać z metody:

GET: antyplagiat.nekst.pl/auth/checkToken?login={login}&md5={md5}

parametry:

• token - token autoryzacyjny
• md5 - skrót klucza dostępowego i tokenu

Stworzenie zadania

Stworzenia nowego zadania dla danego tekstu odbywa się za pomocą metody:

POST: api.antyplagiat.nekst.pl/task/create

parametry:

• token - token autoryzacyjny
• md5 - skrót klucza dostępowego i tokenu
• query - tekst do sprawdzenia (plain/text)
• filename - nazwa pliku

Sprawdzenie statusu zadania

W celu sprawdzenia w jakim stanie znajduje się nasze zadanie należy skorzystać z metody:

GET: antyplagiat.nekst.pl/task/check

parametry:

• token - token autoryzacyjny
• md5 - skrót klucza dostępowego i tokenu
• taskId - identyfikator naszego zadania otrzymany za pomocą metody tworzenia nowego zadania

Pobieranie wyników zadania

Gdy nasze zadanie ma status: DONE można pobrać wyniki korzystając z metody:

GET: antyplagiat.nekst.pl/task/result

parametry:

• token - token autoryzacyjny
• md5 - skrót klucza dostępowego i tokenu
• taskId - identyfikator naszego zadania otrzymany za pomocą metody tworzenia nowego zadania

Dalsze prace

Aktualnie pracujemy nad integracją z ORPPD oraz innymi bazami i systemami (DSpace, Moodle, etc), dlatego API uczelniane zostanie przebudowane, zaś API Nekst zostanie zastąpione uogólnionym API obsługującym zarówno ORPPD, NEKST oraz inne bazy danych.

Zobacz też

• API APD
• Konfiguracja APD
• Spis parametrów konfiguracyjnych
• Uzyskanie dostępu do API NEKST