StaffCoder
Spring Boot
Spring BootSpring Boot 4.1Java 25
12 modules · 48 challengesSign up
Module 6 · DTOs, Mapping and Pagination

Aquarium Species Directory

medium—No data yet

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"
}

More in DTOs, Mapping and Pagination

See the module
Museum Exhibit Management APIThis problem covers shaping what the API returns instead of handing back the stored entity, with a different shape for lists and details.100%1 of 1 solvedmediumVeterinary Visit RecordsThis problem covers loading a record together with its children in a single database statement, without dropping the ones that have no children.0%0 of 1 solvedmediumJob Board Search & PaginationThis problem covers building a query from whichever filters the caller actually supplied, then paging the result.—No data yetmedium

We use cookies that are necessary to run Staffcoder, and optional analytics cookies to see which pages get used. Analytics stays off unless you accept. Read our Cookie Policy.