Dokumentacja API Śpiewnika Niepodległości

Wyjaśnienie sposobu dostępu do danych Śpiewnika Niepodległości poprzez interfejs programistyczny REST oraz licencji dostępu i ponownego użycia treści.

Licencje do treści

Fundacja Dziedzictwa Rzeczypospolitej udostępnia wskazane poniżej zasoby portalu „Śpiewnik Niepodległości” do użytku niekomercyjnego w zamian za uznanie autorstwa treści oraz wskazanie źródła ich uzyskania w ramach licencji Creative Commons.

Szczegółowe zasady są następujące:

Media: audio, zdjęcia

Licencja CC BY-NC-ND

Utwory audiowizualne ze Śpiewnika Niepodległości dostępne są na licencji Creative Commons Uznanie autorstwa – Użycie niekomercyjne – Bez utworów zależnych 4.0 Polski.

Należą do nich:

  • Podkłady muzyczne
  • Nagrania „Koncertu Niepodległości”
  • Zdjęcia, ilustracje i grafiki użyte w portalu.

Teksty, opracowania, nuty

Licencja CC BY-NC-SA

Utwory audiowizualne ze Śpiewnika Niepodległości dostępne są na licencji Creative Commons Uznanie autorstwa – Użycie niekomercyjne – Na tych samych warunkach 4.0 Polski.

Należą do nich:

  • Interpretacje wraz z opisem historycznym utworu
  • Teksty utworów

Nie należą do nich:

  • Strony informacyjne, np. „O projekcie” lub „Dziedzictwo”.

Format danych i wywołania

Sekcja opisuje formaty danych dostępnych przez API oraz sposób odwołania się do nich

Metadane treści oraz mediów Śpiewnika Niepodległości dostępne są jako pod-ścieżki niniejszego adresu głównego API:

https://www.spiewnikniepodleglosci.pl/wp-json/

Aby pobrać dane należy wywołać odpowiedni adres końcowy za pomocą metody HTTP GET z minimalnym zestawem nagłówków.

Dane są zwracane w typie treści (content-type) application/json w kodowaniu (encoding) utf-8.

Typ danych: Lista

Lista przedstawia tablicę wszystkich wpisów Śpiewnika należących do tego samego typu, np. Lista opracowań, Lista nut itp.

Obiekt zawiera minimalnie następujące pola:

  • ID (liczba) – identyfikator listy
  • name (łańcuch znaków) – nazwa listy
  • count (liczba) – ilość wpisów w liście
  • items (tablica obiektów Odnośnik) – lista odnośników do stron

Typ danych: Odnośnik

Odnośnik jest strukturą wskazującą na element utworu określający jego typ, adres oraz identyfikator.

Obiekt zawiera minimalnie następujące pola:

  • object_id (liczba) – identifikator obiektu
  • object (wyliczenie: „page”, „media”) – typ obiektu – determinuje do jakiego API odwołać się po dane obiektu
  • url (łańcuch znaków) – adres URL pod którym obiekt jest dostępny w śpiewniku
  • title (łańcuch znaków) – nazwa obiektu (zdatna do wyświetlania jako treść linku na stronie)

Typ danych: Strona

Typ reprezentujący pojedynczą stronę utworu, jego nut, podkładów itp.

Obiekt zawiera minimalnie następujące pola:

  • id (liczba) – identifikator obiektu
  • date (data ISO-8601) – data lokalna (CET) ostatniej modyfikacji obiektu
  • date_gmt (data ISO-8601) – data UTC/GMT ostatniej modyfikacji obiektu
  • link (łańcuch znaków) – adres URL pod którym obiekt jest dostępny w śpiewniku
  • title (łańcuch znaków) – tytuł strony
  • slug (łańcuch znaków) – zapis tytułu bezpieczny dla systemu plików (bez spacji, polskich znaków diakrytycznych i znaków przestankowych)
  • content (objekt) – pod kluczem „rendered” znajduje się faktyczna treść strony zapisana w formie pseudokodu zawierającego bloki funkcjonalne systemu WP Bakery Composer oraz HTML
  • _links – obiekt zawierający listę linków, w tym klucz „wp:attachment” pod którym znajdują się listy podlinkowanych mediów.

Typ danych: Medium

Typ reprezentujący pojedyncze medium dostępne w Śpiewniku Niepodległości.

Obiekt zawiera minimalnie następujące pola:

  • id (liczba) – identifikator obiektu
  • date (data ISO-8601) – data lokalna (CET) ostatniej modyfikacji obiektu
  • date_gmt (data ISO-8601) – data UTC/GMT ostatniej modyfikacji obiektu
  • title (obiekt) – zawiera jeden klucz „rendered” zawierający tytuł medium
  • slug (łańcuch znaków) – zapis tytułu bezpieczny dla systemu plików (bez spacji, polskich znaków diakrytycznych i znaków przestankowych)
  • media_type (łańcuch) – zawiera typ MIME medium (bez podtypu)
  • mime_type (łańcuch) – zawiera typ i podtyp MIME (np. image/svg+xml)
  • source_url (łańcuch) – zawiera adres pod którym dostępne jest medium (do pobrania)
  • alt_text (łańcuch) – treść alternatywna medium
  • description (obiekt) – zawiera w polu „rendered” treść HTML opisu medium

Punkty docelowe

Lista adresów URL z listami danych Śpiewnika

Lista nut i akordów

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp-api-menus/v2/menus/52

Lista podkładów

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp-api-menus/v2/menus/50

Lista tekstów utworów

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp-api-menus/v2/menus/51

Lista utworów

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp-api-menus/v2/menus/39

Obiekt typu Strona

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp/v2/pages/<object_id>

Obiekt typu Medium

Dostępna jest pod adresem:

https://www.spiewnikniepodleglosci.pl/wp-json/wp/v2/media/<object_id>

Funkcjonalności

Aplikacja oferuje standardowe funkcjonalności CMS WordPress, takie jak graficzna prezentacja przechowywanych danych (teksty, grafika, dokumenty pdf, mp3 itp.), pozwala użytkownikom na wygenerowanie własnych plików na podstawie treści przechowywanych na serwerze.

Dodatkowe funkcjonalności

Ponadto aplikacja oferuje dodatkowe funkcjonalności, których opis znajduje się poniżej.

Kreator Śpiewnika Niepodległości

To narzędzie, które w trzech prostych krokach umożliwia wygenerowanie własnego Śpiewnika Niepodległości.

W pierwszym kroku wybierane są utwory, które znajdą się w Śpiewniku.

W drugim kroku wybierany jest format śpiewnika. Dostępne formaty to PDF, EPUB oraz MOBI. Wybierając format PDF każdy utwór będzie posiadał pakiet materiałów edukacyjnych, na które składają się: pełen tekst utworu, nuty i akordy gitarowe oraz kontekst historyczny powstania utworu. Formaty EPUB oraz MOBI ze względu na swoje ograniczenia zawierają tylko pełen tekst utworu oraz kontekst historyczny powstania utworu. Format EPUB obsługiwany jest przez większość czytników oraz aplikacji. Format MOBI obsługiwany jest przez urządzenia i aplikacje z rodziny Kindle.

W trzecim kroku znajduje się podsumowanie z listą wybranych utworów oraz możliwość podpisania swojego śpiewnika.

W wyniku wygenerowania Śpiewnika następuje utworzenie na serwerze pliku w wybranym formacie oraz utworzenie nowej podstrony, na której znajduje się lista wybranych utworów, podpis jeśli taki został nadany oraz link do pobrania pliku ze śpiewnikiem.

Przycisk „Udostępnij Śpiewnik” pozwala na podzielenie się śpiewnikiem w serwisach społecznościowych Facebook oraz Twitter a także przesłanie wiadomości za pośrednictwem WhatsApp oraz domyślnego klienta pocztowego.

W Kreatorze zastosowany został mechanizm antyspamowy reCAPTCHA, która działając w tle nie wymaga od użytkowników dodatkowych czynności takich jak przepisywanie tekstu czy zaznaczanie obrazków.

Playlisty

To narzędzie pozwala w prosty sposób stworzyć własną playlistę, zawierającą utwory wybrane z bazy Śpiewnika Niepodległości.

W trakcie tworzenia playlisty, oprócz wyboru samych utworów, należy podać tytuł oraz wybrać okładkę. Dodatkowo można podać opis. Wszystkie podane informacje będą widoczne na stronie z utworzoną playlistą, a wybrane utwory będą możliwe do odtworzenia za pomocą wbudowanego playera.

Wygenerowana w ten sposób playlista będzie dostępna na unikalnej podstronie o adresie url utworzonym według schematu nazwa_playlisty-losowyciągznaków/ gdzie nazwa_playlisty to nazwa nadana jej przez użytkownika podczas procesu jej tworzenia, a losowy ciąg znaków to nadawany przez system unikalny ciąg alfanumeryczny o długości 32 znaków.

Na stronie tej znajduje się również przycisk „Udostępnij Playlistę”, który umożliwia podzielenie się śpiewnikiem w serwisach społecznościowych Facebook oraz Twitter a także przesłanie wiadomości za pośrednictwem WhatsApp oraz domyślnego klienta pocztowego.

W generatorze playlist zastosowany został mechanizm antyspamowy reCAPTCHA, która działając w tle nie wymaga od użytkowników dodatkowych czynności takich jak przepisywanie tekstu czy zaznaczanie obrazków.

W razie pytań?

W przypadku pytań lub chęci pozyskania dodatkowej licencji, prosimy o kontakt.