REST API

Trwają prace nad budową katalogu usług sieciowych w arcihtekturze REST z wykorzystaniem formatu danych JSON.
API udostępnia zasoby (encje) poprzez ujednolicone idenryfikatory zasobów (URI). Każdy zbiór danych w POLon posiada swój unikalny identyfikator zasobu, będący angielską nazwą zbioru danych, np. employees, conferences. W projektowanym rozwiązaniu przyjęto konwencję URI przyjaznych człowiekowi (human readable).
Dostęp do danych opiera się na kontach systemu POL-on, aby wykonać operację za pomocą usług REST należy mieć konto z odpowiednią rolą.

API wykorzystuje standardowe metody HTTP do odróżnienia rodzaju operacji:

• GET - pobranie danych
• POST - utworzenie nowego obiektu
• PUT - aktualizacja obiektu (w POL-on rozumiana jako korekta)
• PATCH - częściowa aktualizacja obiektu (w POL-on rozumiana jako zmiana biznesowa)
• DELETE - usunięcie obiektu

W odpowiedziach wykorzystywane są kody statusu HTTP

Katalog usług jest opisany w notacji WADL na stronie: https://polon.nauka.gov.pl/opi-ws.
Dokumentacja jest dostępna pod adresem: https://polon.nauka.gov.pl/api-rest/

Przejdź do katalogu usług

Przejdź do dokumentacji usług

Uwierzytelnianie

Identyfikatory zasobów składają się z części bazowej, tzw. base URI, oraz identyfikatora zasobu, wraz z parametrami.

Każda odpowiedź serwisu będzie zawierała listę obiektów result, zawierającą pola:

• errorCode - kod błędu z POL-on lub zero w przypadku braku błędu
• errorMessage - (opcjonalnie, w przypadku wystąpienia błedu) komunikat błędu
• errorDetails - (opcjonalnie, w przypadku wystąpienia błedu) dodatkowe informacje pomagające w diagnozie błędu

Przykład:

  results: [
    { 
       errorCode: 1961
       errorMessage: "Data zmiany statusu nie może być wcześniejsza niż data poprzedniej zmiany"
    },
    { 
       errorCode: 1942
       errorMessage: "Nie można zmienić statusu nie uwzględnionego na diagramie stanów"
       errorDetails: "status: 'NOT_EXISTS'"
    }
  ]

Informacja o zmianach publikowana jest sukcesywnie wraz z wdrażaniem kolejnych wersji oprogramowania. Lista zmian w API dostępna jest tej stronie

Dla metod GET bezparametrowych (zwracających niefiltrowaną listę obiektów) oraz POST służących do wyszukiwania dostępne jest stronicowanie wyników, służące ograniczeniu rozmiaru listy.
Przy wywołaniu metod GET należy podać pageSize i pageNumber jako parametry w URL, przykładowo wywołanie:

https://example.com/listStuff?pageSize=50&pageNumber=3

zwróci wyniki o numerach od 101 do 150.
Wynik wywołania będzie, poza listą wynikową i listą results, zawierał obiekt pagination:

 pagination: {
     pageSize: 50,
     pageNumber: 3,
     numberOfPages: 5
 }

W przypadku odwołania do strony o numerze przekraczającym całkowitą liczbę stron zostanie zwrócony status HTTP 404 - Not Found.

Obecnie nie obsługiwane.

Konsultacje masowych interfejsów wymiany danych w POL 2.0