Problem statement
Build a REST API for an aquarium species directory, with a paged list view and a detail view loaded in one query.
Requirements
SpeciesListView
Give the list entry one readable property per value a directory entry exposes, and nothing more. These property names are the keys that appear in each list entry, and the list read binds its selected values to them.
- id, the species identifier as a whole number
- commonName as text
- waterType as text
SpeciesRepository
Add the two reads the controller needs:
- A filtered, paged list read producing one directory entry per matching species:
- It reads only the three values a directory entry exposes, selecting them under the property names of SpeciesListView so each result binds to one, rather than loading whole species rows and discarding the rest
- waterType and habitat each keep only the species whose stored value equals the given value, ignoring case on both sides; a value that is absent applies no restriction, and when neither is given every species matches
- Entries come back ordered by commonName ascending
- It reports how many species match, so the envelope totals describe the filtered set rather than the whole table
- A detail read loading one species together with all of its tank assignments in a single database query. A species that has no assignments is still returned rather than dropping out of the result, and an id that matches no species yields no result at all
SpeciesMapper
Implement toDetail to assemble the detail response from a loaded species:
- It carries the species' id, commonName, scientificName, waterType, and habitat, together with its assignments
- Each assignment carries its id, tankName, and since
- The assignments are ordered by since descending, most recent first
SpeciesController
Implement the two REST endpoints. Each must be reachable at exactly the verb and path listed below.
GET /species
- All four query parameters are optional: waterType, habitat, page, and size
- Return 200 OK with one page of directory entries wrapped in an envelope holding exactly the five keys content, page, size, totalElements, and totalPages
- Each entry in content carries exactly id, commonName, and waterType; scientificName, habitat, and careNotes never appear in a list entry
- Entries are ordered by commonName ascending, and that order continues across pages
- The page parameter selects a zero-based page and defaults to 0; size sets the page length and defaults to 10
- totalElements counts every species matching the request, totalPages the number of pages that count fills at the requested size; a page past the last returns 200 OK with an empty content and unchanged totals
- When no species matches, return 200 OK with an empty content, totalElements 0, and totalPages 0
- The waterType and habitat parameters each keep only the species whose stored value equals the parameter; the comparison ignores case on both sides but is exact, so a partial value matches nothing
- The filters compose: either may be used alone, and when both are present a species must satisfy both
- A filter parameter that is omitted, empty, or whitespace-only is ignored
- The totals always describe the filtered set, never the whole table
GET /species/{id}
- Return 200 OK with the full detail of that species: exactly the six keys id, commonName, scientificName, waterType, habitat, and assignments
- assignments holds one object per tank assignment of that species, each carrying exactly id, tankName, and since, ordered by since descending
- Only assignments of the requested species appear
- A species without assignments returns an empty assignments array
- careNotes is stored on every species but is never serialized, neither in the list nor in the detail
- Producing the detail must issue exactly one database query, so the species and all of its assignments arrive together rather than through separate statements
- An id matching no species returns 404 Not Found with error message: "Species not found with id: " followed by the requested id
Sample Requests & Responses
Expand to view details on sample requests and responses.
GET /species
Response (200 OK):
{
"content": [
{
"commonName": "Angelfish",
"waterType": "freshwater",
"id": 3
},
{
"commonName": "Archerfish",
"waterType": "brackish",
"id": 5
},
{
"commonName": "Blue Tang",
"waterType": "saltwater",
"id": 4
},
{
"commonName": "Clownfish",
"waterType": "saltwater",
"id": 1
},
{
"commonName": "Guppy",
"waterType": "freshwater",
"id": 6
},
{
"commonName": "Neon Tetra",
"waterType": "freshwater",
"id": 2
}
],
"page": 0,
"size": 10,
"totalElements": 6,
"totalPages": 1
}
GET /species?size=2&page=1
Response (200 OK):
{
"content": [
{
"commonName": "Blue Tang",
"waterType": "saltwater",
"id": 4
},
{
"commonName": "Clownfish",
"waterType": "saltwater",
"id": 1
}
],
"page": 1,
"size": 2,
"totalElements": 6,
"totalPages": 3
}
GET /species?waterType=freshwater&habitat=river
Response (200 OK):
{
"content": [
{
"commonName": "Angelfish",
"waterType": "freshwater",
"id": 3
},
{
"commonName": "Neon Tetra",
"waterType": "freshwater",
"id": 2
}
],
"page": 0,
"size": 10,
"totalElements": 2,
"totalPages": 1
}
GET /species?waterType=SALTWATER
Response (200 OK):
{
"content": [
{
"commonName": "Blue Tang",
"waterType": "saltwater",
"id": 4
},
{
"commonName": "Clownfish",
"waterType": "saltwater",
"id": 1
}
],
"page": 0,
"size": 10,
"totalElements": 2,
"totalPages": 1
}
GET /species/1
Response (200 OK):
{
"id": 1,
"commonName": "Clownfish",
"scientificName": "Amphiprion ocellaris",
"waterType": "saltwater",
"habitat": "reef",
"assignments": [
{
"id": 3,
"tankName": "Nursery",
"since": "2024-06-01"
},
{
"id": 1,
"tankName": "Reef Alpha",
"since": "2024-03-15"
},
{
"id": 2,
"tankName": "Quarantine Bay",
"since": "2023-11-02"
}
]
}
GET /species/6
Response (200 OK):
{
"id": 6,
"commonName": "Guppy",
"scientificName": "Poecilia reticulata",
"waterType": "freshwater",
"habitat": "Pond",
"assignments": []
}
GET /species/9999
Response (404 Not Found):
{
"error": "Species not found with id: 9999",
"timestamp": "2026-07-30T11:08:10.630330",
"path": "/species/9999"
}
