Interfejs programistyczny aplikacji: Różnice pomiędzy wersjami

Z Otwarty System Antyplagiatowy
Skocz do: nawigacja, szukaj
(Dalsze prace)
(Tworzenie zadań i odbieranie raportów)
 
(Nie pokazano 23 wersji utworzonych przez 3 użytkowników)
Linia 1: Linia 1:
  
Otwarty system antyplagiatowy udostępnia dwa interfejsy komunikacji, jeden do wersji lokalnej instalowanej na komputerze uczelni, drugi do [[System NEKST | Nekst]] umożliwiający sprawdzanie prac w internecie (korzysta z niego wersja lokalna).
+
Otwarty system antyplagiatowy udostępnia interfejs komunikacji do wersji lokalnej instalowanej na komputerze uczelni
  
Obydwa interfejsy zostały wykonane w oparciu o REST (Representational State Transfer).
+
Interfejs zostały wykonany 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]]
  
= API OSA =
+
=== Tworzenie zadań i odbieranie raportów ===
  
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.
+
<pre>POST: http://<adres serwera osa>/api/job/create (dla OSY ver. 3.4.4)
 
+
lub
== Tworzenie zadania ==
+
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)
  
<pre>POST: http://<adres serwera osa>/api/job/create</pre>
+
Uwaga! POST wysyłamy w kodowaniu UTF-8</pre>
  
parametry:
+
parametry (<u>podkreślone są wymagane</u>):
* reportURL    - Adres do przesłania raportu (adres zwrotny)
+
* <u>reportURL</u>     - Adres do przesłania raportu (adres zwrotny)
* university    - Nazwa uniwersytetu
+
* <u>university</u>   - Nazwa uniwersytetu
* polonCode    - Kod POL-on uniwersytetu
+
* <u>polonCode</u>     - Kod POL-on uniwersytetu '''(w tej chwili OSA nie zapisuje tych informacji)'''
* languageCode  - Kod ISO języka pracy
+
* <u>languageCode</u> - Kod ISO języka pracy '''[możliwe pola: pl, en. Parametr tylko informacyjny - nie ma wpływu na wyniki]'''
* documentType  - Typ pracy
+
* documentType  - Typ pracy '''[możliwe pola: licenciate, engineer, master, postgraduate, doctoral, habilitation]'''
* faculty      - Jednostka podstawowa
+
* <u>faculty</u>       - Jednostka podstawowa
* fieldOfStudy  - Kierunek studiów
+
* fieldOfStudy  - Kierunek studiów '''(w tej chwili OSA nie zapisuje tych informacji)'''
 
* knowledgeArea - Obszar wiedzy
 
* knowledgeArea - Obszar wiedzy
* title        - Tytuł pracy
+
* <u>title</u>         - Tytuł pracy
* author        - Autor
+
* <u>author</u>       - Autor
* promoter      - Promotor
+
* <u>promoter</u>     - Promotor
* reviewer      - Recenzent
+
* <u>reviewer</u>     - Recenzent
* file          - Plik
+
* <u>file</u>         - Plik
  
 
odpowiedź:
 
odpowiedź:
Linia 43: Linia 48:
  
 
Mapowanie kodów obszarów:
 
Mapowanie kodów obszarów:
* [OB01] Obszar nauk humanistycznych
+
* OB01 -> Obszar nauk humanistycznych
* [OB02] Obszar nauk społecznych
+
* OB02 -> Obszar nauk społecznych
* [OB03] Obszar nauk ścisłych
+
* OB03 -> Obszar nauk ścisłych
* [OB04] Obszar nauk przyrodniczych
+
* OB04 -> Obszar nauk przyrodniczych
* [OB05] Obszar nauk technicznych
+
* OB05 -> Obszar nauk technicznych
* [OB06] Obszar nauk rolniczych, leśnych i weterynaryjnych
+
* OB06 -> Obszar nauk rolniczych, leśnych i weterynaryjnych
* [OB07] Obszar nauk medycznych i nauk o zdrowiu oraz nauk o kulturze fizycznej
+
* OB07 -> Obszar nauk medycznych i nauk o zdrowiu oraz nauk o kulturze fizycznej
* [OB08] Obszar sztuki
+
* OB08 -> Obszar sztuki
  
= API Nekst =
+
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
  
Serwis REST API znajduje się pod adresem: [https://api.antyplagiat.nekst.pl/ api.antyplagiat.nekst.pl].
+
=== 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'''
  
Komunikacja odbywa się za pomocą protokołu HTTP (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.
+
== 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]]
  
== Autoryzacja ==
+
=== Tworzenie zadań i odbieranie raportów ===
  
W celu uzyskania dostępu do API należy pobrać token autoryzacyjny za pomocą poniższej metody:
+
<pre>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</pre>
  
<pre>GET: antyplagiat.nekst.pl/auth/getToken?login={login}</pre>
+
parametry (<u>podkreślone są wymagane</u>): (content-type: multipart/form-data;)
 +
* <u>action</u>    - Rodzaj zgłoszenia
 +
* <u>reportURL</u>     - Adres do przesłania raportu (adres zwrotny)
 +
* <u>metadata</u>    - Metadane pracy w formacie JSON
 +
* <u>file</u>          - Plik pracy
 +
* guid          - Identyfikator zgłoszenia (wymagane przy action="update")
  
parametry:
+
odpowiedź:
* login - nazwa użytkownika dostarczona przez administratora.
+
* status  - Status zgłoszenia
 
+
* message - Tekstowy komunikat
Każdorazowe wykonanie jakiejkolwiek metody z API wymaga wcześniejszego pobrania nowego tokenu oraz parametru md5 obliczonego według wzoru:
+
* guid    - Identyfikator zgłoszenia
 
+
<pre>$md5 = md5 ( md5 ( $apiKey ) + $tokenFromGetTokenMethod );</pre>
+
 
+
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:
+
 
+
<pre>GET: antyplagiat.nekst.pl/auth/checkToken?login={login}&md5={md5}</pre>
+
 
+
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:
+
 
+
<pre>POST: api.antyplagiat.nekst.pl/task/create</pre>
+
 
+
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:
+
 
+
<pre>GET: antyplagiat.nekst.pl/task/check</pre>
+
  
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 ==
+
Odnośnie '''action''':
 +
new    - standardowe zgłoszenie
 +
update - aktualizacja danych pracy o ID=guid i wysłanie ponownie aktualnego raportu PDF
 +
----
  
Gdy nasze zadanie ma status: DONE można pobrać wyniki korzystając z metody:
+
Odnośnie '''metadata''' w formacie JSON:
 +
<pre>{ 
 +
  "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
 +
      }
 +
  ]
 +
}</pre>
 +
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
  
<pre>GET: antyplagiat.nekst.pl/task/result</pre>
+
== FAQ ==
 +
=== Po wysłaniu requestu metryka pracy nie posiada polskich liter ===
 +
* Wątek na [https://redmine.osaweb.pl/issues/632#change-2575 Redmine] poruszający ten problem dla integracji z systemem DSpace
  
parametry:
+
= Zobacz też =
* token - token autoryzacyjny
+
* [[API APD]]
* md5 - skrót klucza dostępowego i tokenu
+
* [[Konfiguracja APD]]
* taskId - identyfikator naszego zadania otrzymany za pomocą metody tworzenia nowego zadania
+
* [[Spis parametrów konfiguracyjnych]]
 +
* [[Uzyskanie dostępu do Bazy Centralnej]]
  
= Dalsze prace =
 
  
Aktualnie pracujemy nad integracją z [[ORPPD]] oraz innymi bazami, dlatego API uczelniane zostanie przebudowane, zaś API [[System NEKST | Nekst]] zostanie zastąpione uogólnionym API obsługującym zarówno ORPPD, NEKST oraz inne bazy danych.
+
<!--[[Category:tech]]-->

Aktualna wersja na dzień 18:12, 28 lis 2019

Otwarty system antyplagiatowy udostępnia interfejs komunikacji do wersji lokalnej instalowanej na komputerze uczelni

Interfejs zostały wykonany 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, habilitation]
  • 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): (content-type: multipart/form-data;)

  • 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ż