[mikerybka]

That can easily be achieved by not following REST so strictly.

[dragonwriter]

Actually, it can easily be achieved by following REST strictly, especially the part where the key part of REST API design is selecting resources and designing appropriate representations for the intended use.

"REST" as consistently and independent of use case a trivial CRUD layer over base tables is...well, almost as from actual REST as the JSON-based RPC over HTTP version of "REST".

[ec109685]

Sorry, can you provide examples of deeply nested result hierarchies that are expressed well with Rest?

[mhotchen]

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

[lh7]

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?

[wolfgang42]

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>

[lh7]

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

[huherto]

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.

[lh7]

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

[ec109685]

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.

[base698]

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.

[debaserab2]

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.

[nine_k]

Verily!

GraphQL is one way to do just that.

REST has the virtues of uniformity and discoverability. I don't yet understand whether GraphQL possesses any of these too, though.

[sametmax]

In theory yes, in practice, I never saw REST discoverability being used much IRL

[yen223]

GraphQL puts discoverability front and centre, by prioritizing introspection and static typing. GraphiQL (the browser-based GraphQL explorer) is pretty hard to beat.

Check out Github's GraphQL explorer for a great example of this: https://developer.github.com/early-access/graphql/explorer/

[SEJeff]

Because 90% of the "REST" developers don't actually build hypermedia apis, so they aren't really "REST" if you denote "REST" as somewhat complies with Roy Fielding's paper where he invented the acronym REST

[ec109685]

Can you provide standardized examples of REST's uniforms toy and discoverability?

[debaserab2]

https://spring.io/understanding/HATEOAS

[dkersten]

Its worth nothing that Roy Fielding, the guy who coined the term REST, doesn't consider an API RESTful unless it implements HATEOAS. At least, that's what he said in some talk I watched sometime ago.

[SEJeff]

He doesn't consider an API restful unless it is a hypermedia api, of which HATEOAS is an excellent example of.

[zten]

Naming and formatting it differently is an easy way to get away from the REST dogma, though.