Problem statement
Build a REST API for browsing a podcast archive one page at a time, newest episode first.
Requirements
EpisodeController
Every request may carry two optional numeric query parameters, page and size. The endpoint must be reachable at exactly the verb and path listed below.
GET /episodes
- Return 200 OK with a JSON object holding exactly five keys: content, page, size, totalElements, and totalPages
- content is the requested page of episodes, each carrying its id, title, and publishedAt
- Episodes are ordered by publishedAt descending, so the newest episode always comes first and the order carries across pages
- page reports the zero-based page number that was served, size the page size that was applied, totalElements the total number of stored episodes, and totalPages the number of pages the archive spans at that size; for example, 12 episodes at size 5 span 3 pages and the last page holds the remaining 2
- When page is omitted it defaults to 0, the first page
- When size is omitted it defaults to 10
- Requested sizes from 1 through 50 are applied exactly as given
- Any requested size above 50 is clamped to 50: at most 50 episodes are returned and the envelope reports a size of 50
- A page past the end of the archive returns 200 OK with an empty content array while totalElements and totalPages stay correct
- When no episodes are stored, return 200 OK with an empty content array, a totalElements of 0, and a totalPages of 0
- If page is negative, return 400 Bad Request with error message: "Page must be at least 0"; a page of exactly 0 is valid
- If size is less than 1, return 400 Bad Request with error message: "Size must be at least 1"; a size of exactly 1 is valid
- If page or size is not a number, return 400 Bad Request
- Browsing never changes the stored episodes
Sample Requests & Responses
Expand to view details on sample requests and responses.
GET /episodes
Response (200 OK):
{
"content": [
{
"id": 12,
"title": "The Final Broadcast",
"publishedAt": "2026-06-22"
},
{
"id": 11,
"title": "Weather for Insomniacs",
"publishedAt": "2026-06-15"
},
{
"id": 10,
"title": "The Long Interview",
"publishedAt": "2026-06-08"
},
{
"id": 9,
"title": "Paper Trails",
"publishedAt": "2026-06-01"
},
{
"id": 8,
"title": "City of Echoes",
"publishedAt": "2026-05-25"
},
{
"id": 7,
"title": "The Archivist",
"publishedAt": "2026-05-18"
},
{
"id": 6,
"title": "Lost Frequencies",
"publishedAt": "2026-05-11"
},
{
"id": 5,
"title": "The Night Shift Diaries",
"publishedAt": "2026-05-04"
},
{
"id": 4,
"title": "Static and Stories",
"publishedAt": "2026-04-27"
},
{
"id": 3,
"title": "Maps Without Borders",
"publishedAt": "2026-04-20"
}
],
"page": 0,
"size": 10,
"totalElements": 12,
"totalPages": 2
}
GET /episodes?page=1
Response (200 OK):
{
"content": [
{
"id": 2,
"title": "The Lighthouse Tapes",
"publishedAt": "2026-04-13"
},
{
"id": 1,
"title": "Signals from the Deep",
"publishedAt": "2026-04-06"
}
],
"page": 1,
"size": 10,
"totalElements": 12,
"totalPages": 2
}
GET /episodes?page=1&size=5
Response (200 OK):
{
"content": [
{
"id": 7,
"title": "The Archivist",
"publishedAt": "2026-05-18"
},
{
"id": 6,
"title": "Lost Frequencies",
"publishedAt": "2026-05-11"
},
{
"id": 5,
"title": "The Night Shift Diaries",
"publishedAt": "2026-05-04"
},
{
"id": 4,
"title": "Static and Stories",
"publishedAt": "2026-04-27"
},
{
"id": 3,
"title": "Maps Without Borders",
"publishedAt": "2026-04-20"
}
],
"page": 1,
"size": 5,
"totalElements": 12,
"totalPages": 3
}
GET /episodes?size=500
Response (200 OK):
{
"content": [
{
"id": 12,
"title": "The Final Broadcast",
"publishedAt": "2026-06-22"
},
{
"id": 11,
"title": "Weather for Insomniacs",
"publishedAt": "2026-06-15"
},
{
"id": 10,
"title": "The Long Interview",
"publishedAt": "2026-06-08"
},
{
"id": 9,
"title": "Paper Trails",
"publishedAt": "2026-06-01"
},
{
"id": 8,
"title": "City of Echoes",
"publishedAt": "2026-05-25"
},
{
"id": 7,
"title": "The Archivist",
"publishedAt": "2026-05-18"
},
{
"id": 6,
"title": "Lost Frequencies",
"publishedAt": "2026-05-11"
},
{
"id": 5,
"title": "The Night Shift Diaries",
"publishedAt": "2026-05-04"
},
{
"id": 4,
"title": "Static and Stories",
"publishedAt": "2026-04-27"
},
{
"id": 3,
"title": "Maps Without Borders",
"publishedAt": "2026-04-20"
},
{
"id": 2,
"title": "The Lighthouse Tapes",
"publishedAt": "2026-04-13"
},
{
"id": 1,
"title": "Signals from the Deep",
"publishedAt": "2026-04-06"
}
],
"page": 0,
"size": 50,
"totalElements": 12,
"totalPages": 1
}
GET /episodes?page=9&size=5
Response (200 OK):
{
"content": [],
"page": 9,
"size": 5,
"totalElements": 12,
"totalPages": 3
}
GET /episodes?page=-1
Response (400 Bad Request):
{
"error": "Page must be at least 0",
"timestamp": "2026-07-30T10:46:46.941768",
"path": "/episodes"
}
GET /episodes?size=0
Response (400 Bad Request):
{
"error": "Size must be at least 1",
"timestamp": "2026-07-30T10:46:47.128587",
"path": "/episodes"
}
GET /episodes?size=abc
Response (400 Bad Request):
{
"timestamp": "2026-07-30T05:01:47.301+00:00",
"status": 400,
"error": "Bad Request",
"path": "/episodes"
}
