
How OneGraph onboards users who are new to GraphQL - dwwoelfel
https://www.onegraph.com/blog/2019/01/24/How_OneGraph_onboards_users_new_to_GraphQL.html
======
abhisuri97
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
> 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.

------
mrspeaker
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
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/m...](https://github.com/OneGraph/graphiql-explorer-
example/blob/master/src/CustomArgs.js#L42)

------
sbr464
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
I have also run into this issue.

I use a hand-written generator which generates a "AllXXFields" fragment for
each type automatically.

~~~
sgrove
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
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
        }
      }
    }

~~~
sbr464
Saw there was a library from OpenTable[1] that generated queries from
introspection:

[1] [https://github.com/opentable/graphql-query-
generator](https://github.com/opentable/graphql-query-generator)

------
AznHisoka
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.

~~~
yen223
Calling an endpoint is only half the story. You still need to know the shape
of the response. And most rest APIs I've had to use do a suboptimal job at
communicating the schema of the response.

Even Stripe's API, which is far ahead of most other APIs in terms of
documentation, doesn't tell you basic things like whether a field can ever be
null.

GraphQL defines an interface for describing the schema of an endpoint. This to
me is the most valuable thing about it.

~~~
sgrove
This is a great point - Stripe is one of the exceptional companies that
maintains a _great_ openapi spec though!

Even so, the GraphQL experience (with the explorer and some other OSS releases
we have for next week) is still just so exciting
[https://serve.onegraph.com/short/Q8SE4F](https://serve.onegraph.com/short/Q8SE4F)
:D

    
    
       query search {
         stripe {
           invoices(first: 10) {
             nodes {
               amountDue
               nextPaymentAttempt
               object
               total
               customer {
                 ... on StripeCustomer {
                   id
                   email
                 }
               }
               charge {
                 dispute {
                   created
                   reason
                   status
                 }
               }
             }
           }
         }
       }
    

\- Type (and nullability!) of fields

\- In-situ documentation on what the fields are for

\- Ability to navigate the Stripe graph from any starting point (customer ->
charges -> cards) in a single super-efficient call

\- Search-ability across the whole Stripe API in a single field

\- Potentially joins across services, e.g. from Stripe to Zendesk or
Salesforce

And so on and so on!

------
jeremynevans
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.

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

~~~
dabit3
In that case you may be interested in AWS AppSync (a managed GraphQL service)

[https://aws.amazon.com/appsync/](https://aws.amazon.com/appsync/)

------
NicoJuicy
I've used graphql ( by force) in the past.

I like odata a lot more, but it's more initial work

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

~~~
sgrove
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.

