I use JSON API which allows for "compound documents" instead of deeply nested results[1]. I would say it's well expressed, and it doesn't violate any of the principles of REST.

[1] http://jsonapi.org/format/#document-compound-documents

I am not sure I follow the conversation. What would a deeply nested result hierarchy be, exactly?

Are we talking about something like:

CREATE TABLE person (id INT, name TEXT, birthdate DATE);

CREATE TABLE car (id INT, brand TEXT, model TEXT, licence TEXT);

CREATE TABLE p_c (pid INT, cid INT, FOREIGN KEY pid REFERENCES person (id), FOREIGN KEY cid REFERENCES car (id));

And for a given person, we want to return their details plus the cars they own?

gopher://example.com/person/{id}

# Get person ID

1, Joe, 1970-01-01

gopher://example.com/car/{id}

# Get car ID

1, Ford, T, 1313

gopher://example.com/person/{id}/cars

# Get all cars owned by person ID

1, Joe, 1970-01-01, 1 Ford, T, 1313

,,, 2 Ford, S, 1717

gopher://example.com/person/{id}/cars/{id}

# Get specific car

gopher://example.com/car/{id}/owners

# Get owner(s) of car ID

gopher://example.com/car/{id}/owners/{id}

# Get specific owner

gopher://example.com/car/{id}/owners/{id}/birthdate

# Get specific owner's birthdate

gopher://example.com/car/{id}/owners/birthdate

# Get birthdate of all owners (assuming no domain overlap between IDs and field names, other solutions possible otherwise)

If this is the sort of thing we're talking about, I've got that t-shirt and assumed everyone had too, so I guess I'm missing the point here. By how much?

You seem to have messed up the format of your RFC4266 gopher:// urls. The first character of the path is the type, not part of the selector. Neither types 'c' nor 'p' are standardized, but I believe the convention is that they are calendar and ASCII-based page-layout documents, respectively.

I'm not sure what the correct type actually is, though. For JSON the closest RFC1436 type is probably 0, though I would be inclined to consider using (non-standard) type j instead.

</pedantic>

Indeed, it's been a long time and it wasn't common to actually use URLs back then!

Thanks for the example. I am also trying to wrap my head around it.

Is it possible to get all that information in one round trip ? I believe that is one of the benefits of graphQL.

> Is it possible to get all that information in one round trip ?

If we're talking about the same thing, yes.

One pattern that I use in my APIs is as follows:

Assume a JSON object like:

{ name: "Joe", colour: [ {red: 0, green: 128, blue: 90}, {red: 35, green: 88, blue: 199} ], hair: { length: { value: 9, uom: "cm"} }

I have on occasion provided an API like:

# Assume that {id} returns an object like the above.

GET /api/{id} # Returns the full object

POST /api/{id} # Replaces the object

PUT /api/{id} # Overwrites properties in the object

GET /api/{id}/name # Returns "Joe"

POST /api/{id}/name # Overwrites the name

PUT /api/{id}/name # Overwrites the name (also)

DELETE /api/{id}/name # Removes the "name" property

GET /api/{id}/colour/0/green # Returns "green". Other methods as above.

* /api/{id}/hair/length/value

PUT /api/{id}/hair/colour # Creates a new property

GET /api/{id}/colour/0;2 # Returns the first and third items in the array

GET /api/{id}/colour/1/red;green # Returns those two properties from the object. Note that this imposes some restrictions on property naming (no semicolons)

And this I never implemented, but I would if I had a need:

GET /api/{id}/colour/(0/red;green);(1/blue) # Returns [ { red: 0, green: 128}, {blue: 199} ]

The problem is that you are making up the syntax. GraphQL gives you this power in a standard that is machine readable so tools can be built around it.

Seems that way, with the added benefit of the client specifying the fields they need. Valuable if the underlying API changes to add a field but the clients can't use it yet.

I find that if I'm having to deeply nest result hierarchies into my REST payload I probably haven't spent a lot of time thinking about how the API I am building will be consumed. Usually designing my endpoints to align more closely with the concepts consumers of the API expect prevents the need to nest a lot of data. You may have to break your endpoints away from your data structures somewhat and reorganize your API into the logical structures that more closely represent the way interactions are performed in your software.

That's not to discount GraphQL, because I think it clearly has it's use cases, especially at Facebook size.