6 ms·

How OneGraph onboards users who are new to GraphQL

118 points by dwwoelfel 8y ago

abhisuri97 8y ago
I don't think necessarily GraphQL is hard to understand as a concept. It's just difficult to figure out how to use it in an actual app context. How do I handle more complicated things such as authentication and, more importantly, what are acceptable and secure ways to structure your queries for auth (and things like that). I can certainly hack around with `context`, I just don't know what is actually good or not.
- sgrove 8y ago
  > I don't think necessarily GraphQL is hard to understand as a concept It was surprising to us as well! But working with lots of users who are new to GraphQL, there are a few speed bumps along the way before you get to "implementing GraphQL in production." You have to convince your GraphQL users that: 1. It won't take too long to understand 2. It will be worth the effort Anything you can do to make building a valid GraphQL query (both syntactically and semantically) faster helps with #1, and will get your users further along. Making it so that users can see success/data flowing in as quickly as possible helps with #2. From there, like you mentioned, there are lots of additional challenges, but for this post we're focusing on getting new users over the most initial hurdles.
- headcanon 8y ago
  I don't know what the stack you're working with looks like, but authentication can be done the same way as a REST API would - wherever you have your top-level handler that receives the HTTP request can accept/reject the request if it is invalid. So for example, you'd use the same express middleware you would normally if that was your stack. Its a bit simpler to wrap your head around from that perspective if you just think of it as any other POST request. Authorization, that is, allowing users access to some things but not others, is more complicated and of course bespoke to your application. The simple solution is to simply check context in individual resolvers, which ends up looking a lot like a normal Express/Flask/Sinatra app. There is a graphql-middleware package that helps structure "middleware" resolvers, and a graphql-shield package that helps with more complicated role-based logic.
- PostThisTooFast 8y ago
  I was excited about GraphQL; but it doesn't seem to handle the majority of queries I need to do, which involve joins. I know other people have encountered the same issue with GraphQL. What's the solution? Thanks!
AznHisoka 8y ago
Naive question: Is GraphQL meant to be used only by the frontend developers to consume backend data, etc? And not by the actual consumers of the API (ie customers, users)? If not, I don't see why consumers would ever want to use GraphQL. Figuring out the syntax/language to do something as simple as retrieving the first X items requires more thought than calling a dead-simple REST endpoint.
- iamjaredwalters 8y ago
  > more thought than calling a dead-simple REST endpoint REST shortcomings aren't necessarily found in a single api request. REST's shortcomings are the handful of endpoints required to get the information you actually want.
  - dragonwriter 8y ago
    > REST's shortcomings are the handful of endpoints required to get the information you actually want. That's a problem of a naive CRUD API against a normalized relational datastore (or one structurally resembling such a store) regardless of architectural style, but there is no reason any standardized packet of information for which there is an expected recurring need should not be conceptualized as a resource in a REST API. Orthogonality or normalization is not part of the REST architectural style.
    - jonreem 8y ago
      This approach necessitates an ever growing number of increasingly specific APIs, or an ever growing set of flags and options which will inevitably approximate a poorly implemented version of GraphQL.
      - iamjaredwalters 8y ago
        Exactly. Eventually eroding REST away to "RESTful".
- dwwoelfel 8y ago
timwis 8y ago
For me the barriers have been implementing the server (especially with authorisation logic); consuming it as a client was the relatively easy part.
- dabit3 8y ago
  In that case you may be interested in AWS AppSync (a managed GraphQL service) https://aws.amazon.com/appsync/ https://aws.amazon.com/appsync/
- tirumaraiselvan 8y ago
  Also check out Hasura (https://hasura.io https://hasura.io) which works on any Postgres anywhere. Hasura provides out-of-the-box GraphQL APIs which you can extend as well while hooking into any (web-based) external Auth system for role based access control. Full Disclosure: I work at Hasura.
sbr464 8y ago
I’m a big fan of graphql and use it for all frontend work. I ran into one issue recently from a server side client use case where I needed to quickly consume an entire endpoint. Since you need to define each field in your query, it was more time consuming to create the requests. I also see the issue if fields are added, you would miss that data without updating your query. Typically these are benefits when doing frontend work, to limit data, but I did find it annoying when just needing to quickly dump data. For my own servers moving forward, I’m going to be adding a _doc json field for users that need traditional rest endpoint functionality in a query.
- the_duke 8y ago
  I have also run into this issue. I use a hand-written generator which generates a "AllXXFields" fragment for each type automatically.
  - sgrove 8y ago
    We're thinking of adding a "add all" checkbox in the explorer for this exact reason - feel free to open an issue https://github.com/OneGraph/graphiql-explorer/issues https://github.com/OneGraph/graphiql-explorer/issues so we can discuss it further. There are obviously tradeoffs that come with selecting all fields by default (in particular it makes it difficult for the server devs to send thoughtful notifications only to clients who rely on specific fields when necessary), but for initially exploring it's definitely nice.
    - sbr464 8y ago
      Thinking about a solution, to stay within the "graphql way", I was thinking of doing this: 1. Send introspection queries[1] to get the schema. 2. Iterate over the results, building a query object with all of the non deprecated fields. 3. Store the results in a db or cache for later queries. 4. Send the request as normal with the full query. https://graphql.org/learn/introspection/ https://graphql.org/learn/introspection/ [1] Example introspection query: query { __schema { types { name kind } } } query { __type(name: "YourTypeName") { name kind fields { name type { name kind ofType { name kind } } description isDeprecated deprecationReason } } }
NicoJuicy 8y ago
I've used graphql ( by force) in the past. I like odata a lot more, but it's more initial work
mrspeaker 8y ago
This is really cool! I think that for the demo you should make the "Explorer" open by default - I bet most people won't realize what to do otherwise and will be intimidated (and just leave). If possible it would be good to add default values too (like the "ticker" in the stock data set)!
- dwwoelfel 8y ago
  Good idea! Just pushed up a change to open the explorer by default and fill in a default value for the stock ticker. The explorer supports adding args that should be auto-checked and providing default values. It could probably be a little easier to use, but it's easy enough to add new ones once you have an example: https://github.com/OneGraph/graphiql-explorer-example/blob/master/src/CustomArgs.js#L42 https://github.com/OneGraph/graphiql-explorer-example/blob/m...
- pitzahoy 8y ago
  X2 this comment!
silentguy 8y ago
Is there any way to download OneGraph GraphiQL explorer binary? Is it open source?
- sgrove 8y ago
  We haven't made any custom GraphiQL for the desktop yet, I think we'll reach out to e.g. https://altair.sirmuel.design https://altair.sirmuel.design to see if we can get it to ship with OneGraph "preconfigured" with all of the open-source additions we're adding right now.
jeremynevans 8y ago
I've been a OneGraph user for a while now and I have to say the Explorer feature is still one of my favourite things about it. In my opinion, a well designed API should be as easy to explore as folders on a computer, and the GraphiQL Explorer makes this the case by default.

118 points by dwwoelfel 8y ago

I don't think necessarily GraphQL is hard to understand as a concept. It's just difficult to figure out how to use it in an actual app context. How do I handle more complicated things such as authentication and, more importantly, what are acceptable and secure ways to structure your queries for auth (and things like that). I can certainly hack around with `context`, I just don't know what is actually good or not.

sgrove 8y ago
> I don't think necessarily GraphQL is hard to understand as a concept It was surprising to us as well! But working with lots of users who are new to GraphQL, there are a few speed bumps along the way before you get to "implementing GraphQL in production." You have to convince your GraphQL users that: 1. It won't take too long to understand 2. It will be worth the effort Anything you can do to make building a valid GraphQL query (both syntactically and semantically) faster helps with #1, and will get your users further along. Making it so that users can see success/data flowing in as quickly as possible helps with #2. From there, like you mentioned, there are lots of additional challenges, but for this post we're focusing on getting new users over the most initial hurdles.
headcanon 8y ago
I don't know what the stack you're working with looks like, but authentication can be done the same way as a REST API would - wherever you have your top-level handler that receives the HTTP request can accept/reject the request if it is invalid. So for example, you'd use the same express middleware you would normally if that was your stack. Its a bit simpler to wrap your head around from that perspective if you just think of it as any other POST request. Authorization, that is, allowing users access to some things but not others, is more complicated and of course bespoke to your application. The simple solution is to simply check context in individual resolvers, which ends up looking a lot like a normal Express/Flask/Sinatra app. There is a graphql-middleware package that helps structure "middleware" resolvers, and a graphql-shield package that helps with more complicated role-based logic.
PostThisTooFast 8y ago
I was excited about GraphQL; but it doesn't seem to handle the majority of queries I need to do, which involve joins. I know other people have encountered the same issue with GraphQL. What's the solution? Thanks!

AznHisoka 8y ago

Naive question: Is GraphQL meant to be used only by the frontend developers to consume backend data, etc? And not by the actual consumers of the API (ie customers, users)? If not, I don't see why consumers would ever want to use GraphQL. Figuring out the syntax/language to do something as simple as retrieving the first X items requires more thought than calling a dead-simple REST endpoint.

iamjaredwalters 8y ago
> more thought than calling a dead-simple REST endpoint REST shortcomings aren't necessarily found in a single api request. REST's shortcomings are the handful of endpoints required to get the information you actually want.
- dragonwriter 8y ago
  > REST's shortcomings are the handful of endpoints required to get the information you actually want. That's a problem of a naive CRUD API against a normalized relational datastore (or one structurally resembling such a store) regardless of architectural style, but there is no reason any standardized packet of information for which there is an expected recurring need should not be conceptualized as a resource in a REST API. Orthogonality or normalization is not part of the REST architectural style.
  - jonreem 8y ago
    This approach necessitates an ever growing number of increasingly specific APIs, or an ever growing set of flags and options which will inevitably approximate a poorly implemented version of GraphQL.
    - iamjaredwalters 8y ago
      Exactly. Eventually eroding REST away to "RESTful".
dwwoelfel 8y ago

timwis 8y ago

For me the barriers have been implementing the server (especially with authorisation logic); consuming it as a client was the relatively easy part.

dabit3 8y ago
In that case you may be interested in AWS AppSync (a managed GraphQL service) https://aws.amazon.com/appsync/ https://aws.amazon.com/appsync/
tirumaraiselvan 8y ago
Also check out Hasura (https://hasura.io https://hasura.io) which works on any Postgres anywhere. Hasura provides out-of-the-box GraphQL APIs which you can extend as well while hooking into any (web-based) external Auth system for role based access control. Full Disclosure: I work at Hasura.

sbr464 8y ago

I’m a big fan of graphql and use it for all frontend work. I ran into one issue recently from a server side client use case where I needed to quickly consume an entire endpoint. Since you need to define each field in your query, it was more time consuming to create the requests. I also see the issue if fields are added, you would miss that data without updating your query. Typically these are benefits when doing frontend work, to limit data, but I did find it annoying when just needing to quickly dump data. For my own servers moving forward, I’m going to be adding a _doc json field for users that need traditional rest endpoint functionality in a query.

the_duke 8y ago
I have also run into this issue. I use a hand-written generator which generates a "AllXXFields" fragment for each type automatically.
- sgrove 8y ago
  We're thinking of adding a "add all" checkbox in the explorer for this exact reason - feel free to open an issue https://github.com/OneGraph/graphiql-explorer/issues https://github.com/OneGraph/graphiql-explorer/issues so we can discuss it further. There are obviously tradeoffs that come with selecting all fields by default (in particular it makes it difficult for the server devs to send thoughtful notifications only to clients who rely on specific fields when necessary), but for initially exploring it's definitely nice.
  - sbr464 8y ago
    Thinking about a solution, to stay within the "graphql way", I was thinking of doing this: 1. Send introspection queries[1] to get the schema. 2. Iterate over the results, building a query object with all of the non deprecated fields. 3. Store the results in a db or cache for later queries. 4. Send the request as normal with the full query. https://graphql.org/learn/introspection/ https://graphql.org/learn/introspection/ [1] Example introspection query: query { __schema { types { name kind } } } query { __type(name: "YourTypeName") { name kind fields { name type { name kind ofType { name kind } } description isDeprecated deprecationReason } } }

NicoJuicy 8y ago

I've used graphql ( by force) in the past. I like odata a lot more, but it's more initial work

mrspeaker 8y ago

This is really cool! I think that for the demo you should make the "Explorer" open by default - I bet most people won't realize what to do otherwise and will be intimidated (and just leave). If possible it would be good to add default values too (like the "ticker" in the stock data set)!

dwwoelfel 8y ago
Good idea! Just pushed up a change to open the explorer by default and fill in a default value for the stock ticker. The explorer supports adding args that should be auto-checked and providing default values. It could probably be a little easier to use, but it's easy enough to add new ones once you have an example: https://github.com/OneGraph/graphiql-explorer-example/blob/master/src/CustomArgs.js#L42 https://github.com/OneGraph/graphiql-explorer-example/blob/m...
pitzahoy 8y ago
X2 this comment!

silentguy 8y ago

Is there any way to download OneGraph GraphiQL explorer binary? Is it open source?

sgrove 8y ago
We haven't made any custom GraphiQL for the desktop yet, I think we'll reach out to e.g. https://altair.sirmuel.design https://altair.sirmuel.design to see if we can get it to ship with OneGraph "preconfigured" with all of the open-source additions we're adding right now.

jeremynevans 8y ago

I've been a OneGraph user for a while now and I have to say the Explorer feature is still one of my favourite things about it. In my opinion, a well designed API should be as easy to explore as folders on a computer, and the GraphiQL Explorer makes this the case by default.