Pagination links in Rest API

Introduction

Pagination links help break large lists of data into smaller pages. This makes it easier and faster to get and show data step by step.

When you have many items and want to show only a few per page in an app or website.

When your API returns a long list and you want to let users get data page by page.

When you want to save bandwidth by sending smaller chunks of data.

When you want to improve user experience by loading data faster in parts.

Syntax

Rest API

Link: <https://api.example.com/items?page=2&size=10>; rel="next",
      <https://api.example.com/items?page=5&size=10>; rel="last"

Each link is inside angle brackets <> and followed by a rel attribute describing its role.

Common rel values are next, prev, first, and last.

Examples

Only the next page link is provided.

Rest API

Link: <https://api.example.com/items?page=2&size=10>; rel="next"

Links for first, previous, and last pages are included.

Rest API

Link: <https://api.example.com/items?page=1&size=10>; rel="first",
      <https://api.example.com/items?page=3&size=10>; rel="prev",
      <https://api.example.com/items?page=5&size=10>; rel="last"

Sample Program

This Flask app returns items in pages. It adds Link headers with URLs for next and previous pages if available.

Rest API

from flask import Flask, request, jsonify, url_for

app = Flask(__name__)

items = list(range(1, 51))  # 50 items

@app.route('/items')
def get_items():
    page = int(request.args.get('page', 1))
    size = int(request.args.get('size', 10))
    start = (page - 1) * size
    end = start + size
    data = items[start:end]

    links = []
    if end < len(items):
        next_url = url_for('get_items', page=page + 1, size=size, _external=True)
        links.append(f'<{next_url}>; rel="next"')
    if page > 1:
        prev_url = url_for('get_items', page=page - 1, size=size, _external=True)
        links.append(f'<{prev_url}>; rel="prev"')

    link_header = ', '.join(links)

    response = jsonify(data)
    if link_header:
        response.headers['Link'] = link_header
    return response

# To run the app, use: flask run

# Example request: GET /items?page=2&size=10

Important Notes

Pagination links are usually sent in the HTTP Link header.

Clients use these links to navigate pages without building URLs themselves.

Always include rel to describe the link's purpose clearly.

Summary

Pagination links split data into pages for easier access.

They use URLs with rel attributes like next and prev.

APIs send these links in the Link header to guide clients.

Practice

1. What is the main purpose of pagination links in a REST API?

easy

A. To split large data into smaller pages for easier access

B. To encrypt the data sent from the server

C. To speed up the server response time by caching

D. To validate user authentication tokens

Solution

1. Step 1: Understand pagination concept

   Pagination divides large data sets into smaller, manageable pages.

2. Step 2: Identify purpose of pagination links

   Pagination links help clients navigate between these pages easily.

3. Final Answer:

   To split large data into smaller pages for easier access -> Option A

4. Quick Check:

   Pagination = split data into pages [OK]

Hint: Pagination means breaking data into pages for easy reading [OK]

Common Mistakes:

• Confusing pagination with data encryption
• Thinking pagination speeds up server response
• Mixing pagination with authentication

2. Which of the following is the correct syntax for a pagination link in an HTTP header?

easy

A. Link: ; rel="next"

B. Link: https://api.example.com/items?page=2 rel=next

C. Link: rel=next

D. Link: https://api.example.com/items?page=2; rel="next"

Solution

1. Step 1: Review correct Link header format

   The URL must be enclosed in angle brackets <> and rel value in quotes.

2. Step 2: Match syntax with options

   Link: ; rel="next" correctly uses <URL> and rel="next" with quotes.

3. Final Answer:

   Link: <https://api.example.com/items?page=2>; rel="next" -> Option A

4. Quick Check:

   Link header syntax = <URL>; rel="value" [OK]

Hint: Use angle brackets for URL and quotes for rel value [OK]

Common Mistakes:

• Omitting angle brackets around URL
• Not quoting the rel attribute value
• Missing semicolon between URL and rel

3. Given the HTTP Link header:
Link: <https://api.example.com/items?page=3>; rel="next", <https://api.example.com/items?page=1>; rel="prev"
What URL should the client use to get the previous page?

medium

A. https://api.example.com/items?page=3

B. https://api.example.com/items?page=4

C. https://api.example.com/items?page=1

D. https://api.example.com/items?page=2

Solution

1. Step 1: Identify rel attributes in Link header

   Rel="next" points to page 3, rel="prev" points to page 1.

2. Step 2: Find URL for previous page

   The client should use the URL with rel="prev", which is page 1.

3. Final Answer:

   https://api.example.com/items?page=1 -> Option C

4. Quick Check:

   Prev page URL = page=1 [OK]

Hint: Look for rel="prev" to find previous page URL [OK]

Common Mistakes:

• Choosing the next page URL instead of previous
• Confusing page numbers in URLs
• Ignoring rel attribute values

4. You receive this Link header:
Link: https://api.example.com/items?page=2; rel="next"
Why might this cause an error when parsing pagination links?

medium

A. The page number is invalid

B. The rel attribute value is missing quotes

C. The semicolon is missing between URL and rel

D. The URL is not enclosed in angle brackets

Solution

1. Step 1: Check Link header syntax rules

   URLs must be enclosed in angle brackets <> for correct parsing.

2. Step 2: Identify error in given header

   The URL is not inside <>, which can cause parsing errors.

3. Final Answer:

   The URL is not enclosed in angle brackets -> Option D

4. Quick Check:

   URL must be in <> for Link header [OK]

Hint: Always put URLs in angle brackets in Link headers [OK]

Common Mistakes:

• Forgetting angle brackets around URLs
• Assuming quotes around rel are optional
• Misplacing semicolons in header

5. You want to implement pagination links for an API returning 100 items with 10 items per page. Which Link header correctly provides navigation for page 5?

hard

A. Link: ; rel="next", ; rel="prev"

B. Link: ; rel="next", ; rel="prev"

C. Link: ; rel="next", ; rel="prev"

D. Link: ; rel="next", ; rel="prev"

Solution

1. Step 1: Calculate next and previous pages for page 5

   Next page after 5 is 6, previous page before 5 is 4.

2. Step 2: Match correct URLs with rel attributes

   Link: ; rel="next", ; rel="prev" correctly assigns page=6 to rel="next" and page=4 to rel="prev".

3. Final Answer:

   Link: <https://api.example.com/items?page=6>; rel="next", <https://api.example.com/items?page=4>; rel="prev" -> Option B

4. Quick Check:

   Page 5 next=6, prev=4 [OK]

Hint: Next page = current +1, prev page = current -1 in Link header [OK]

Common Mistakes:

• Swapping next and prev URLs
• Using current page number for both next and prev
• Incorrect page numbers outside valid range