Designing a URL-based query syntax for GraphQL(blog.logrocket.com)
blog.logrocket.com
Designing a URL-based query syntax for GraphQL
https://blog.logrocket.com/designing-url-based-query-syntax-graphql/
27 comments
PQL looks like a cracked out parrot ran across my keyboard:
Reasoning about the query as a literal string instead of _data_ is where I think this went off the rails. I probably would have just added middleware to allow for base64 encoded queries and then gone that route. A query can get deterministically hashed into a string of chars.
/?
query=
posts(
ids: [1, 1499, 1178],
order: $order
)@posts.
id|
date(format: d/m/Y)|
title<
skip(if: false)
>|
--props&
order=title|ASC&
props=
url|
author.
name|
url
Reasoning about the query as a literal string instead of _data_ is where I think this went off the rails. I probably would have just added middleware to allow for base64 encoded queries and then gone that route. A query can get deterministically hashed into a string of chars.
[deleted]
Might be me but I don't see the alternative as readable either. There's also a bunch of knowledge specific to that format which makes it almost tribal if you've not got a reference handy.
Seems like an unnecessary layer of abstraction to me. If I'm in a webbrowser anyway, it's much easier to open the console, write decodeURIComponent(`<your_encoded_query_here>`) and look at the decoded query rather than having to translate PQL to GraphQL syntax in my head, especially since the GraphQL will be a nicely formatted multi-line string whereas the PQL is single-line.
I have dabbled with the same problem with AgoRapide which offers queries through GET (although on a much simpler level than PQL / GraphQL).
I just present the query in readable form together with the output, letting the user choose between copy / paste the URL or copy / paste the readable form.
Example:
http://arnorthwind.agorapide.com/RQ/dt/Order/WHERE%20Shipped...
will present the alternative form
See more examples at http://arnorthwind.agorapide.com/
I just present the query in readable form together with the output, letting the user choose between copy / paste the URL or copy / paste the readable form.
Example:
http://arnorthwind.agorapide.com/RQ/dt/Order/WHERE%20Shipped...
will present the alternative form
Order
WHERE ShippedDate = Today
SELECT OrderId, ShippedDate, CustomerId, Customer.CompanyName, OrderDetail.Sum.Sum() AS SumOrder
See more examples at http://arnorthwind.agorapide.com/
What is wrong with Odata?
Odata v4 with json payloads is more or less how most would define the payload manually, it has all the benefits of GraphQL (retrieving a tree of objects, selecting required attributes), is fully compatible with Rest (retrieves are GETs, mutations can be POST, PUT, DELETE), has a true query language with filtering, aggregations, expressions, joins, paging, sorting, which are all part of the url so you can cache it like a normal Rest GET, has batches so you can update multiple objects in one transactions, and supports subscriptions so you can receive updates instantaniously...
Odata v4 with json payloads is more or less how most would define the payload manually, it has all the benefits of GraphQL (retrieving a tree of objects, selecting required attributes), is fully compatible with Rest (retrieves are GETs, mutations can be POST, PUT, DELETE), has a true query language with filtering, aggregations, expressions, joins, paging, sorting, which are all part of the url so you can cache it like a normal Rest GET, has batches so you can update multiple objects in one transactions, and supports subscriptions so you can receive updates instantaniously...
I think the reason why graphql is currently winning is tooling. GraphiQL, schema-aware+caching clients for front end frameworks and fragments are all things that could exist for OData or JSON-API or whatnot, but i don‘t think they do. Ember has something nice for JSON-API I believe, and you can generate various clients from your Swagger spec, but It doesn‘t look like the same thing.
It‘s not great that paging, sorting and filtering aren‘t speced in graphql, so something better could be appealing.
If OData had something along the lines of urql graphcache and a good pattern for composing 1 screen query from component fragments I‘d be interested, but I‘m not going to write it.
Also, as people like to point out, GraphQL is really some kind of RPC, which is actually pretty handy. Most ad hoc HTTP api‘s are as.well, but once you enter a more well defined spec, do you still have that flexibility to just "get things done"?
It‘s not great that paging, sorting and filtering aren‘t speced in graphql, so something better could be appealing.
If OData had something along the lines of urql graphcache and a good pattern for composing 1 screen query from component fragments I‘d be interested, but I‘m not going to write it.
Also, as people like to point out, GraphQL is really some kind of RPC, which is actually pretty handy. Most ad hoc HTTP api‘s are as.well, but once you enter a more well defined spec, do you still have that flexibility to just "get things done"?
I evaluated GraphQL for a Django back end project this week. We currently use Django Rest Framework. I also explored the current REST landscape and OData came up.
I understand why OData isn't seen more.
For example compare graphql.org www.odata.org. It's a huge difference. The GraphQL landing page is up front on what it does and how it can help you. OData has this:
> OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs.
What is this supposed to tell me? To me it doesn't sound like OData is a committee based REST api and that's not a pro in my book.
There were other things that led me to not consider it as a viable option: - the OData format doesn't look clean and nice, OData fields and function calls - the framework support in python is practically nonexistent
And I still don't know which problems it actually tries to solve. If you could tell me, I'm more than happy to listen.
I understand why OData isn't seen more.
For example compare graphql.org www.odata.org. It's a huge difference. The GraphQL landing page is up front on what it does and how it can help you. OData has this:
> OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs.
What is this supposed to tell me? To me it doesn't sound like OData is a committee based REST api and that's not a pro in my book.
There were other things that led me to not consider it as a viable option: - the OData format doesn't look clean and nice, OData fields and function calls - the framework support in python is practically nonexistent
And I still don't know which problems it actually tries to solve. If you could tell me, I'm more than happy to listen.
It's a standardized way of doing Rest. Has most of the performance benefits of GraphQL (improve performance by reducing roundtrips and flexible way of specifying what objects and attributes you need), and then some. See examples on this page: https://www.odata.org/getting-started/basic-tutorial/
You can use Rest resources like database tables, with filtering, sorting, paging, do RPC style requests like GraphQL with Odata actions, or do data replication with odata subscriptions.
Biggest benefits to me are: 1) is a Rest protocol, instead of something on top of Http like Soap or GraphQL, 2) sql like resource access helps random access to data in different apps using standard reporting tooling like Excel and PowerBi, and 3) rich metadata which helps clients understand what they can do with the Odata resource (filterable, sortable, pageable, countable, etc).
You can use Rest resources like database tables, with filtering, sorting, paging, do RPC style requests like GraphQL with Odata actions, or do data replication with odata subscriptions.
Biggest benefits to me are: 1) is a Rest protocol, instead of something on top of Http like Soap or GraphQL, 2) sql like resource access helps random access to data in different apps using standard reporting tooling like Excel and PowerBi, and 3) rich metadata which helps clients understand what they can do with the Odata resource (filterable, sortable, pageable, countable, etc).
Thanks for you short explanation.
[deleted]
I’ve only played with a a bit of ODATA but it seems quite under appreciated. I think I’ve only seen it in (some of) Microsoft’s APIs.
The main problem was that it was invented by Microsoft.
I could've sworn I've seen something like this before... oh! Oh! XPath[0]!
[0]: https://en.wikipedia.org/wiki/XPath
[0]: https://en.wikipedia.org/wiki/XPath
Ok but https://www.w3.org/TR/rdf-sparql-query/ seems to suffer from the same problems as GraphQL, maybe people don't actually care what the query looks like URL encoded as you generally have tools that tell you actually what the query is.
This is clever! Can anyone help me understand how this lines up with the original value proposition of GraphQL? I was under the impression that the Big Idea behind GraphQL was, amongst other things, client-side caching [1]. I’m probably missing some nuance here, so bear with me: if your GraphQL client is caching properly, then what would this syntax give a developer that a URL query parameter parser couldn’t?
[1] https://graphql.org/learn/caching/
[1] https://graphql.org/learn/caching/
The idea of GraphQL via GET is great, but I'm not sure of the value of optimising for readable URLs. I honestly don't find that syntax much more readable than single-line GraphQL. That's fine though, because honestly who needs to write queries manually in the URL anyway? Everyone is either going to be using a library, or GraphiQL.
I‘m sure you already know but it‘s worth pointing out:
GET queries are already part of the specification, or rather the "Serving over HTTP" recommendations (?) and it’s well supported. The only difference is they don‘t look as nice.
GET queries are already part of the specification, or rather the "Serving over HTTP" recommendations (?) and it’s well supported. The only difference is they don‘t look as nice.
Why is having url query params be human readable a requirement?
Non devs do not care one bit about the query params, and devs don't write them by hand so who cares?
Non devs do not care one bit about the query params, and devs don't write them by hand so who cares?
Clever, but this solution feels like the space pen to base64's pencil. :)
Now this is a version of graphql i can get behind.
This is absurd.
Transmitting and displaying text in two dimensions has been a solved problem since the teleprinter was invented in the 1920s.
Transmitting and displaying text in two dimensions has been a solved problem since the teleprinter was invented in the 1920s.
> PQL is a superset of the GraphQL query syntax.
This is so obviously wrong.
This is so obviously wrong.
I love GraphQL and I loathe how URLs look. This is a neat concept.
This is not necessary
what problem does this solve?
It also conveniently leaves out automatic persisted queries which would replace queries with hashes, or regular persisted queries, where we'd have a limited set of allowed queries on the server-side that it accepts.
I think ultimately when I think of sending GET requests for GraphQL, I'm immediately more worried about the URL length limit. The risk being that at some point in the future we may run over this limit and get into a lot of unexpected trouble.
Also, this article assumes that you can only stringify GraphQL a single way, with spaces. However a not as commonly known detail in the spec is that any commas are treated the same as whitespaces. Hence, this is a valid query:
Which isn't far off from reading a complex query string IMO, works with any existing GraphQL API via GET if the API already accepts GET requests, and isn't a special format that'll need to be learned supporting the full syntax.