REST API - paginacja wyników odpowiedzi

Więcej w temacie REST API

• Model dojrzałości REST API Leonarda Richardsona
• Odstępstwa od zasad REST API

Paginacja czyli dziel i zarządzaj

Paginacja wyników REST API jest kluczowym elementem projektowania API, zwłaszcza gdy mowa o obsłudze dużych zestawów danych. Jest to proces dzielenia zestawu wyników na mniejsze segmenty, zwane stronami (nie koniecznie stronami - o czym niżej). Istnieje kilka powodów, dla których paginacja jest ważna i korzystna zarówno dla dostawców API, jak i ich użytkowników:

1. Zwiększenie wydajności: Bez paginacji, żądanie wszystkich dostępnych rekordów naraz może obciążyć serwer, co prowadzi do długiego czasu oczekiwania na odpowiedź i może nawet spowodować przeciążenie serwera. Porcjowanie pozwala na ograniczenie liczby danych przesyłanych w jednym żądaniu, co zmniejsza obciążenie serwera i przyspiesza czas odpowiedzi.

2. Zmniejszenie zużycia zasobów: Przesyłanie dużych ilości danych jednorazowo może być kosztowne pod względem zużycia pasma i zasobów obliczeniowych, zarówno dla serwera, jak i klienta. Paginacja pomaga ograniczyć to zużycie, zapewniając dane w mniejszych, bardziej zarządzalnych porcjach.

3. Poprawa doświadczenia użytkownika: Z punktu widzenia użytkownika, ładowanie dużych ilości danych na raz może być przytłaczające i nieefektywne. Paginacja pozwala użytkownikom na łatwiejsze nawigowanie przez dane i koncentrację na mniejszej liczbie elementów na raz, co może poprawić ogólne doświadczenie korzystania z aplikacji.

4. Elastyczność w dostępie do danych: Paginacja umożliwia użytkownikom dostęp do określonych segmentów danych, na przykład do określonej strony wyników, bez konieczności przeglądania wszystkich danych od początku. Umożliwia to bardziej elastyczne i efektywne korzystanie z danych.

5. Zarządzanie zmianami w danych: W dynamicznych zestawach danych, gdzie rekordy mogą być dodawane, aktualizowane lub usuwane, paginacja może pomóc w zarządzaniu spójnością danych prezentowanych użytkownikowi. Używając technik takich jak paginacja oparta na kursorze, aplikacje mogą lepiej radzić sobie ze zmianami w danych, zapewniając użytkownikom bardziej aktualny widok.

Paginacja może być realizowana na różne sposoby

Termin "paginacja" odnosi się do podziału wyników uzyskiwanych ze źródła danych na strony, ale nie musi być rozumiana dosłownie, jak to jest w przypadku książek. Porcjowanie danych może odbywać się według różnych algorytmów w zależności od potrzeb.

W REST API i nie tylko najpopularniejsze rodzaje paginacji to:

• Paginacja oparta na numerze strony: Gdzie klient żąda określonej strony danych, podając numer strony i rozmiar strony (np. strona 2, rozmiar strony 10) /products?page=2&page_size=10

• Paginacja oparta na przesuwaniu: Gdzie klient żąda określonej ilości rekordów począwszy od wskazanej pozycji. W przypadku /messages?top=5&skip=17 parametr top wskazuje na to ile maksymalnie wiadomości chcę uzyskać począwszy od 18 wiadomości ponieważ pierwsze 17 powinno zostać pominiętych.

• Paginacja oparta o znacznik czasu (timestamp): Gdzie klient żąda porcji danych począwszy od wpisu najbliższego wskazanemu znacznikowi czasu. Znacznikiem czasu może być bieżąca data i godzina ale może to być również dowolny punkt w przeszłości /me/feed?limit=25&since=1364849754

• Paginacja oparta na kursorze: Gdzie klient żąda danych, zaczynając od określonego punktu (np. po ostatnim otrzymanym identyfikatorze) i określa, ile elementów chce otrzymać /posts?limit=10&cursor=<post_id> - czytaj to chcę dziesięć kolejnych postów zaczynając od posta o podanym ID.

Dobór odpowiedniego sposobu paginacji zależy od specyfiki projektu lub raczej określonego źródła danych gdyż w ramach jednego projektu możemy stosować różne algorytmy. Dobrym przykładem jest Facebook, który już dawno wyskoczył poza standardy REST API, ale zawsze można podejrzeć jak jego developerzy implementują różne rozwiązania - w tym wypadku podział treści na mniejsze porcje.

Implementacja paginacji z użyciem nagłówka Range

Jest możliwe zaimplementowanie paginacji w REST API z użyciem nagłówków HTTP, takich jak Range, choć nie jest to typowe podejście i może mieć pewne ograniczenia. Nagłówek Range jest tradycyjnie używany w protokole HTTP do określenia częściowego pobierania treści, na przykład w przypadku dużych plików binarnych, ale może być również zaadaptowany do paginacji danych.

Mimo że ta metoda jest technicznie możliwa, ma kilka ograniczeń i powodów, dla których nie jest zalecana:

1. Kompleksowość i niejasność: Użycie nagłówków Range i Content-Range dla paginacji danych nie jest standardowym podejściem i może być mylące dla deweloperów, którzy są przyzwyczajeni do bardziej typowych metod paginacji, jak parametry zapytania URL.

2. Ograniczona użyteczność: Użycie nagłówka utrudnia testowanie w przeglądarce. Nie wystarczy adres URL, trzeba jeszcze podać nagłówek zatem koniecznym staje się użycie Postmana, curl albo innego narzędzia.

3. Utrudnione buforowanie: Mechanizmy cache bardzo często działają w oparciu o strukturę adresu URL i mogą nie uwzględniać parametrów paginacji przesyłanych za pośrednictwem nagłówka.

4. Zgodność z istniejącymi klientami i serwerami proxy: Niektóre klienty HTTP oraz serwery proxy mogą nie być przygotowane na interpretację nagłówków Range i Content-Range poza ich tradycyjnym zastosowaniem do plików binarnych, co może powodować problemy z kompatybilnością.

Informacja o paginacja zawarta w odpowiedzi

W REST API, informacje o paginacji są często zawarte w nagłówkach odpowiedzi HTTP lub jako część ciała odpowiedzi, wraz z linkami do następnych/poprzednich stron danych.

Paginacja za pomocą nagłówków odpowiedzi

Informacje o paginacji są zawarte w nagłówkach odpowiedzi HTTP. Na przykład, serwer może używać nagłówków Link do wskazywania poprzednich i następnych stron, a nagłówków X-Total-Count do informowania o całkowitej liczbie dostępnych zasobów.

# Żądanie klienta
GET /api/posts?page=2&limit=10

# Odpowiedź serwera
Content-Type: application/json X-Total-Count: 100 Link: <https://example.com/api/posts?page=1&limit=10>; rel="prev",       <https://example.com/api/posts?page=3&limit=10>; rel="next"

Paginacja w ciele odpowiedzi

W tym podejściu, informacje o paginacji są bezpośrednio zawarte w ciele odpowiedzi JSON. To ułatwia klientom dostęp do tych informacji bez potrzeby parsowania nagłówków.

# Żądanie klienta
GET /api/posts?page=2&limit=10

# Odpowiedź serwera
{
  "posts": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 10,
    "total_items": 100,
    "next_page": "https://example.com/api/posts?page=3&limit=10",
    "prev_page": "https://example.com/api/posts?page=1&limit=10"
  }
}

Oba podejścia są powszechnie stosowane i wybór między nimi zależy od preferencji, wymagań projektowych i konwencji w danym API.

Informacje o paginacji dostarczane w ciele odpowiedzi lub w nagłówkach, szczególnie gdy zawierają linki do poprzednich i następnych stron, są elementem HATEOAS.