How to design an API that returns nested lists?

Question

I am retrieving GeoPoints from a database and organize them for usage in frontend. The GeoPoints are aggregated in segments, the segments in layers, the layers are mapped to drive ids and that map is maped to car ids. The frontend displays all of that nicely, with Tooltips and such.

My REST GetMapping method looks like this.

public ResponseEntity<Map<Integer, Map<Integer, List<List<List<double[]>>>>>>

For new colleagues, this is insanely hard to understand. But I can't think of any other way to do it. Should I create dummy child classes of Map and List just so I can write something like

public ResponseEntity<CarMap<Integer, DriveMap<Integer, Layers<Segments<GeoPoints<double[]>>>>>>

How is something like this handled typically?

Answer 1

For new colleagues, this is insanely hard to understand

Yeah, no kidding. I'm surprised anyone understands it.

Why are you not using actual classes?

public ResponseEntity<List<Car>> myMethod { ... }

class Car
{
    private final int id;
    private final List<Drive> drives;
}

class Drive
{
    private final int id;
    private final List<Layer> layers;
}

class Layer
{
    private final List<Segment> segments;
}

class Segment
{
    private final List<GeoPoint> geopoints;
}

class GeoPoint
{
    private final List<Double> points;
}