10 ms·

How to GraphQL – A Fullstack Tutorial for GraphQL

276 points by evo_9 8y ago

jasonm89 8y ago
Looks interesting! Gonna give the react + apollo and graphql-ruby tutorials a go.
analogmemory 8y ago
This looks awesome. I've been wanting to get a good understanding of how to use GraphQL.
isoos 8y ago
I was very interested about build a fullstack GraphQL system, but early on, I've got the feeling that if you are using a strongly typed language, which has its proper data binding layers (to the DB or to the UI components), then there are very little benefits of using GraphQL. Could somebody share their thought on that? I mean, I get that react(-like) UI frameworks or node.js servers are happy using it, as this is their version of creating a "narrow" interface. However most platforms do support powerful type-to-serialization mappings through either reflection or code generation. We can create "narrow" interfaces easily, and these can be used with much less hassle than GraphQL. Can somebody share their story if/when GraphQL were beneficial with a strongly typed language?
- adamkl 8y ago
  We've actually gone the opposite direction. We start with our GraphQL schema and then generate TypeScript types off of that schema. This is something that's often done on the client side, but we do it on the server side. With those, we get type safety on input arguments, and can make sure that our data access layer maps from back-end data sources to our output GraphQL types.
  - ex3ndr 8y ago
    Can you share what exactly you are generating for server? Asking for a friend :)
    - adamkl 8y ago
      We actually built an internal tool (shamelessly called create-graphql-service) that scaffolds a new graphql service and includes generation of TypeScript types as part of the build process [1]. [1] https://gist.github.com/adamkl/27539b3a8129f23e3576bfc37b3ea235 https://gist.github.com/adamkl/27539b3a8129f23e3576bfc37b3ea...
- waterfoul 8y ago
  It's really helpful when you have many desperate systems which all hit the same API in different ways. We've built a more custom solution to hit some existing databases and this style of system will be reducing the need for as much custom c# code on each back end. It's also SUPER useful because it will auto-gen the types for our api calls and we no longer have to hand write them. I do see your point though, for existing apps which alreayd have the infrastructure in place this style of system is not as helpful, it's mostly geared at new development and common apis
  - isoos 8y ago
    There are many ways that one can define a custom, narrow interface for a service, and automatically generate client code, server stub, and for many cases even database access codes. GraphQL is one of them, it may be one of the not-too-lame ones, but for most practical purposes, it doesn't seem to be clearly better than the average toolkit.
adamkl 8y ago
Just a disclaimer here, and I don't want to ruffle any feathers, but this tutorial has been put together by the graphcool/prisma team and promotes the use of their Prisma GraphQL/ORM/Database product. I've used some of their tools (and I am even working on a library that would be a good compliment to Prisma), but don't come out of this tutorial thinking that Prisma is some sort of defacto standard back-end for GraphQL APIs.
- augbog 8y ago
  yup great point thanks for calling that out. I appreciate they made their tutorial free though.
deleted 8y ago
[deleted]
ex3ndr 8y ago
What most of the tutorials are usually missing is versioning and schema hygiene. I am building APIs for last 6(?) years and in graphql there are no clean way to have different versions (intentionally) and after only half year of rapid iteration over ideas in my startup our scheme became a mess. I can spend hours trying to figure out how to fix my scheme now (my bad) and i think that this is much more important than basics - they can be easily learned by reading graphql.org.
- y4mi 8y ago
  i don't have a lot of experience with graphql, but your api is hopefully already running behind a reverse proxy... Just run two instances on /api/v1 and /api/v2. Or use the parameters to specify a version.. but I think the reverse proxy solution is cleaner
  - ex3ndr 8y ago
    Sure, but this is not a very clean way. Reverse proxy is not a problem for sure, but writing Resolvers will be a huge pain with no way to make something hacky that won't blow up the whole server.
ulkesh 8y ago
What’s really missing is that every single GraphQL tutorial glosses over the server. Sure there’s a chapter on it. A whole chapter. There are no good articles on server best practices, how best to use ORM with it (especially as it relates to lazy loading), etc. While we are going full board with GraphQL, we’re having to really fly by the seats of our collective pants because practical GraphQL serving is a far cry from idiomatic GraphQL. Some of us have more complicated applications than NEWHOPE, EMPIRE, and JEDI.
- schickling 8y ago
  This is a fantastic point! Co-creator of How to GraphQL here. I’m very excited to tell you that we’re currently working on a new iteration of the page and content that will include more in-depth chapters about dataloaders, authentication, authorization and other advanced topics. Would be great to hear more thoughts on which topics you’d like to see covered.
  - pjmlp 8y ago
    For me to even start thinking about GraphQL instead of REST, there needs to exist Java, .NET and C++ mature libraries for GraphQL at the same level of available REST ones. Using JavaScript ones is not an option. So that is the kind of thing I would care about.
    - monch1962 8y ago
      I would add Python and Go to that set of required, mature server-side libraries. If there's solid libraries for each of the common languages used to write serverless code, then I think that'd be a big plus for decision makers who are on the fence about adopting GraphQL
      - pjmlp 8y ago
        Sure, I was only listing the ones from my toolbox. :)
  - 8y ago
mikece 8y ago
Is it just me or is "full stack GraphQL" a bit of a misnomer? Both on the server/cloud-side as well as the client side (not just JavaScript but binary mobile and desktop apps too) the approaches and libraries for GraphQL are almost legion. Would be nice if there was a type of card catalog resource for GraphQL so that whether your shop is EmberJS and Django or Angular6 and .NET Core or Kotlin/Android Studio and Spring you could be given a pointer to the relevant tutorials for the approaches/libraries/options for your chosen client and server-side technology. (Yes, I realize this link is sort of that but less complete on the server-side stacks -- where is .NET? -- and lacking native mobile and desktop consideration).
- adamkl 8y ago
  I think one of the reasons why there are so many different approaches and libraries out there is due in part to what GraphQL is. Its both more, and less, than an alternative to a REST API. Its primary use case right now is to replace a REST API, but at its heart, GraphQL is a specification for a type system, query language and the semantics to resolve one against the other. I can’t speak to other implementations, but graphql-js gives you the tools to parse queries and schemes into abstract syntax trees, and once you have that, there’s a lot you can do. With those tools, people have been creating all sorts of things. Take a look at Apollo’s work on merging schemas together for a good example. [1] Personally, I’m working on a proxy layer that will sit in front of a GraphQL API and act as a sort of business rule engine. It analyses the incoming queries to figure out which sets of rules need to be run. These sorts of solutions don’t have anything to do with APIs. Heck, you could create a GraphQL schema to act as a classic data access layer, and call it internally from your own code... Which is what Prisma is doing. I think this ability to leverage the capabilities of GraphQL to create innovative new solutions muddies the waters for those who are looking to create a simple API. [1] https://www.apollographql.com/docs/graphql-tools/schema-stitching.html https://www.apollographql.com/docs/graphql-tools/schema-stit...
Azeralthefallen 8y ago
I recently moved one of our API's from Loopback to GraphQL using Postgraphile. It has been a nightmare. - Access restrictions, and security is very painful. Trying to enforce RBAC through postgresql policies over hundreds of tables with slightly different policies is a nightmare. Hiding all this on the DB's end and burying this stuff in migrations sucks for anyone trying to develop on it. - I still have not found a good solution to querying/filtering over things like nested JSONB objects without writing my own resolver functions, which then complicates numerous things. - Versioning is a mess, especially when you don't have an easy way to force clients to upgrade (i.e. mobile apps), along with other parties using your graphql api directly. - However the worst thing so far to me has been i have watched as UI developers go from writing simple rest queries, and doing a bit of work on the front-end to writing extremely inefficient and convoluted queries. Even worse is when a third party is doing it and i have no say over what they do with it.
- ioddly 8y ago
  Have you looked at Hasura's postgres offering at all? I haven't used either yet, but I spoke to one of the founders a while back and auth difficulties was one of the things we talked about. I believe they're open sourcing their data layer soon.
- adamkl 8y ago
  This just sounds like you are missing required layers of your application. I haven't used Postgraphile, but it sounds like you are just exposing your database directly out through a GraphQL wrapper. You'd be experiencing the same pain if you tried this approach with any API technology (gRPC, REST, SOAP, etc). You should still have code for authorization and business logic, and your API should probably be exposing a focused subset of your data model unless your clients really need to be able to traverse the entire database.
  - Azeralthefallen 8y ago
    Except utilizing loopback i simply define my models, what fields are exposed by models, and their relationships. I can easily implement RBAC restrictions via a simple access hook or ACL's. To me having to maintain two separate graphql services for a single API seems extremely convoluted. I can't expose the private api to any other internal services, because all the authorization and restrictions are done on the application layer. To me isn't that just using a GraphQL server as an ORM? To me that seems like an extremely roundabout way to do something like that.
fizb 8y ago
from the tutorial: const typeDefs = ` type Query { info: String! feed: [Link!]! } type Link { id: ID! description: String! url: String! } ` Why is this rubbish in backticks accepted? It is especially stunning to see this in "modern" ES6+ code explaining the newest hype. It's not even mentioned that it sucks, it's presented like proper code.
- tomnipotent 8y ago
  Because it's a string?
  - danlugo92 8y ago
    It could be done in a type safe manner as opposed to magic strings.
    - argestes 8y ago
      Yeah you can do SQL with Hibernate too. It works but it's a nightmare
    - tomnipotent 8y ago
      No, because it's meant to be a declarative language and not ECMA-based. At least spend five minutes understanding what something is before throwing shade.
kellysutton 8y ago
Do we need GraphQL? https://kellysutton.com/2017/01/02/do-we-need-graphql.html https://kellysutton.com/2017/01/02/do-we-need-graphql.html (Disclaimer: From my personal blog)
- acjohnson55 8y ago
  The problems you outline are real, but have straightforward solutions. You can persist queries to the server and then GET them in a really natural way, using query params to provide arguments for your GraphQL query's variables. Then, when it comes to caching, just do it at the resolver level, using something like DataLoader, perhaps with a KV store.
  - lolive 8y ago
    For the Semantic Web, I developped a query repository and a query builder GUI (cf datao.net). And my frontend (search.datao.net) fetches thoses queries and apply them upon resource IDs it receives from a search engine.
jaequery 8y ago
I can see the praise of Graphql especially when coming from frontend developers. I do enjoy working with them at the client side level. But at the backend level, I find Graphql bit too verbose. There is a lot of code being repeated (or referenced) and it makes your code bloated with having to manage several different places. For example if you have a customers table, you have to declare the fields you have in the table for the schema, then you declare them all again on the queries/mutations/resolvers. Which are again repeated at the client side. So if you ever alter something in your table, you have to touch around 4-5 files for each change. You then multiply that by the number of tables you have and you get the idea. It is essentially worse if your database schema have quite a bit of nested JSON data. Sure there are pros and cons to this but atleast with me, so far, the cons seem to outweigh the pros. I miss being able to whip up an API endpoint on the fly. Graphql backend coding reminds me of the days of SOAP with the WSDL and all, I recall it made me hate coding. I was thrilled to see REST get popularized and get away from SOAP completely. Now it seems we are back in a quasi-SOAP world again with Graphql. I'm sure it's a bit more improved now but once being burned I just don't feel comfortable going back to anything that resembles it. I generally like simple and quick solutions that addresses problems. But Graphql seems like it's in the other spectrum of it. On the bright side, Graphql is somewhat fun. :)

276 points by evo_9 8y ago

jasonm89 8y ago

Looks interesting! Gonna give the react + apollo and graphql-ruby tutorials a go.

analogmemory 8y ago

This looks awesome. I've been wanting to get a good understanding of how to use GraphQL.

isoos 8y ago

I was very interested about build a fullstack GraphQL system, but early on, I've got the feeling that if you are using a strongly typed language, which has its proper data binding layers (to the DB or to the UI components), then there are very little benefits of using GraphQL. Could somebody share their thought on that? I mean, I get that react(-like) UI frameworks or node.js servers are happy using it, as this is their version of creating a "narrow" interface. However most platforms do support powerful type-to-serialization mappings through either reflection or code generation. We can create "narrow" interfaces easily, and these can be used with much less hassle than GraphQL. Can somebody share their story if/when GraphQL were beneficial with a strongly typed language?

adamkl 8y ago
We've actually gone the opposite direction. We start with our GraphQL schema and then generate TypeScript types off of that schema. This is something that's often done on the client side, but we do it on the server side. With those, we get type safety on input arguments, and can make sure that our data access layer maps from back-end data sources to our output GraphQL types.
- ex3ndr 8y ago
  Can you share what exactly you are generating for server? Asking for a friend :)
  - adamkl 8y ago
    We actually built an internal tool (shamelessly called create-graphql-service) that scaffolds a new graphql service and includes generation of TypeScript types as part of the build process [1]. [1] https://gist.github.com/adamkl/27539b3a8129f23e3576bfc37b3ea235 https://gist.github.com/adamkl/27539b3a8129f23e3576bfc37b3ea...
waterfoul 8y ago
It's really helpful when you have many desperate systems which all hit the same API in different ways. We've built a more custom solution to hit some existing databases and this style of system will be reducing the need for as much custom c# code on each back end. It's also SUPER useful because it will auto-gen the types for our api calls and we no longer have to hand write them. I do see your point though, for existing apps which alreayd have the infrastructure in place this style of system is not as helpful, it's mostly geared at new development and common apis
- isoos 8y ago
  There are many ways that one can define a custom, narrow interface for a service, and automatically generate client code, server stub, and for many cases even database access codes. GraphQL is one of them, it may be one of the not-too-lame ones, but for most practical purposes, it doesn't seem to be clearly better than the average toolkit.

adamkl 8y ago

Just a disclaimer here, and I don't want to ruffle any feathers, but this tutorial has been put together by the graphcool/prisma team and promotes the use of their Prisma GraphQL/ORM/Database product. I've used some of their tools (and I am even working on a library that would be a good compliment to Prisma), but don't come out of this tutorial thinking that Prisma is some sort of defacto standard back-end for GraphQL APIs.

augbog 8y ago
yup great point thanks for calling that out. I appreciate they made their tutorial free though.

deleted 8y ago

[deleted]

ex3ndr 8y ago

What most of the tutorials are usually missing is versioning and schema hygiene. I am building APIs for last 6(?) years and in graphql there are no clean way to have different versions (intentionally) and after only half year of rapid iteration over ideas in my startup our scheme became a mess. I can spend hours trying to figure out how to fix my scheme now (my bad) and i think that this is much more important than basics - they can be easily learned by reading graphql.org.

y4mi 8y ago
i don't have a lot of experience with graphql, but your api is hopefully already running behind a reverse proxy... Just run two instances on /api/v1 and /api/v2. Or use the parameters to specify a version.. but I think the reverse proxy solution is cleaner
- ex3ndr 8y ago
  Sure, but this is not a very clean way. Reverse proxy is not a problem for sure, but writing Resolvers will be a huge pain with no way to make something hacky that won't blow up the whole server.

ulkesh 8y ago

What’s really missing is that every single GraphQL tutorial glosses over the server. Sure there’s a chapter on it. A whole chapter. There are no good articles on server best practices, how best to use ORM with it (especially as it relates to lazy loading), etc. While we are going full board with GraphQL, we’re having to really fly by the seats of our collective pants because practical GraphQL serving is a far cry from idiomatic GraphQL. Some of us have more complicated applications than NEWHOPE, EMPIRE, and JEDI.

schickling 8y ago
This is a fantastic point! Co-creator of How to GraphQL here. I’m very excited to tell you that we’re currently working on a new iteration of the page and content that will include more in-depth chapters about dataloaders, authentication, authorization and other advanced topics. Would be great to hear more thoughts on which topics you’d like to see covered.
- pjmlp 8y ago
  For me to even start thinking about GraphQL instead of REST, there needs to exist Java, .NET and C++ mature libraries for GraphQL at the same level of available REST ones. Using JavaScript ones is not an option. So that is the kind of thing I would care about.
  - monch1962 8y ago
    I would add Python and Go to that set of required, mature server-side libraries. If there's solid libraries for each of the common languages used to write serverless code, then I think that'd be a big plus for decision makers who are on the fence about adopting GraphQL
    - pjmlp 8y ago
      Sure, I was only listing the ones from my toolbox. :)
- 8y ago

mikece 8y ago

Is it just me or is "full stack GraphQL" a bit of a misnomer? Both on the server/cloud-side as well as the client side (not just JavaScript but binary mobile and desktop apps too) the approaches and libraries for GraphQL are almost legion. Would be nice if there was a type of card catalog resource for GraphQL so that whether your shop is EmberJS and Django or Angular6 and .NET Core or Kotlin/Android Studio and Spring you could be given a pointer to the relevant tutorials for the approaches/libraries/options for your chosen client and server-side technology. (Yes, I realize this link is sort of that but less complete on the server-side stacks -- where is .NET? -- and lacking native mobile and desktop consideration).

adamkl 8y ago
I think one of the reasons why there are so many different approaches and libraries out there is due in part to what GraphQL is. Its both more, and less, than an alternative to a REST API. Its primary use case right now is to replace a REST API, but at its heart, GraphQL is a specification for a type system, query language and the semantics to resolve one against the other. I can’t speak to other implementations, but graphql-js gives you the tools to parse queries and schemes into abstract syntax trees, and once you have that, there’s a lot you can do. With those tools, people have been creating all sorts of things. Take a look at Apollo’s work on merging schemas together for a good example. [1] Personally, I’m working on a proxy layer that will sit in front of a GraphQL API and act as a sort of business rule engine. It analyses the incoming queries to figure out which sets of rules need to be run. These sorts of solutions don’t have anything to do with APIs. Heck, you could create a GraphQL schema to act as a classic data access layer, and call it internally from your own code... Which is what Prisma is doing. I think this ability to leverage the capabilities of GraphQL to create innovative new solutions muddies the waters for those who are looking to create a simple API. [1] https://www.apollographql.com/docs/graphql-tools/schema-stitching.html https://www.apollographql.com/docs/graphql-tools/schema-stit...

Azeralthefallen 8y ago

I recently moved one of our API's from Loopback to GraphQL using Postgraphile. It has been a nightmare. - Access restrictions, and security is very painful. Trying to enforce RBAC through postgresql policies over hundreds of tables with slightly different policies is a nightmare. Hiding all this on the DB's end and burying this stuff in migrations sucks for anyone trying to develop on it. - I still have not found a good solution to querying/filtering over things like nested JSONB objects without writing my own resolver functions, which then complicates numerous things. - Versioning is a mess, especially when you don't have an easy way to force clients to upgrade (i.e. mobile apps), along with other parties using your graphql api directly. - However the worst thing so far to me has been i have watched as UI developers go from writing simple rest queries, and doing a bit of work on the front-end to writing extremely inefficient and convoluted queries. Even worse is when a third party is doing it and i have no say over what they do with it.

ioddly 8y ago
Have you looked at Hasura's postgres offering at all? I haven't used either yet, but I spoke to one of the founders a while back and auth difficulties was one of the things we talked about. I believe they're open sourcing their data layer soon.
adamkl 8y ago
This just sounds like you are missing required layers of your application. I haven't used Postgraphile, but it sounds like you are just exposing your database directly out through a GraphQL wrapper. You'd be experiencing the same pain if you tried this approach with any API technology (gRPC, REST, SOAP, etc). You should still have code for authorization and business logic, and your API should probably be exposing a focused subset of your data model unless your clients really need to be able to traverse the entire database.
- Azeralthefallen 8y ago
  Except utilizing loopback i simply define my models, what fields are exposed by models, and their relationships. I can easily implement RBAC restrictions via a simple access hook or ACL's. To me having to maintain two separate graphql services for a single API seems extremely convoluted. I can't expose the private api to any other internal services, because all the authorization and restrictions are done on the application layer. To me isn't that just using a GraphQL server as an ORM? To me that seems like an extremely roundabout way to do something like that.

fizb 8y ago

from the tutorial: const typeDefs = ` type Query { info: String! feed: [Link!]! } type Link { id: ID! description: String! url: String! } ` Why is this rubbish in backticks accepted? It is especially stunning to see this in "modern" ES6+ code explaining the newest hype. It's not even mentioned that it sucks, it's presented like proper code.

tomnipotent 8y ago
Because it's a string?
- danlugo92 8y ago
  It could be done in a type safe manner as opposed to magic strings.
  - argestes 8y ago
    Yeah you can do SQL with Hibernate too. It works but it's a nightmare
  - tomnipotent 8y ago
    No, because it's meant to be a declarative language and not ECMA-based. At least spend five minutes understanding what something is before throwing shade.

kellysutton 8y ago

Do we need GraphQL? https://kellysutton.com/2017/01/02/do-we-need-graphql.html https://kellysutton.com/2017/01/02/do-we-need-graphql.html (Disclaimer: From my personal blog)

acjohnson55 8y ago
The problems you outline are real, but have straightforward solutions. You can persist queries to the server and then GET them in a really natural way, using query params to provide arguments for your GraphQL query's variables. Then, when it comes to caching, just do it at the resolver level, using something like DataLoader, perhaps with a KV store.
- lolive 8y ago
  For the Semantic Web, I developped a query repository and a query builder GUI (cf datao.net). And my frontend (search.datao.net) fetches thoses queries and apply them upon resource IDs it receives from a search engine.

jaequery 8y ago

I can see the praise of Graphql especially when coming from frontend developers. I do enjoy working with them at the client side level. But at the backend level, I find Graphql bit too verbose. There is a lot of code being repeated (or referenced) and it makes your code bloated with having to manage several different places. For example if you have a customers table, you have to declare the fields you have in the table for the schema, then you declare them all again on the queries/mutations/resolvers. Which are again repeated at the client side. So if you ever alter something in your table, you have to touch around 4-5 files for each change. You then multiply that by the number of tables you have and you get the idea. It is essentially worse if your database schema have quite a bit of nested JSON data. Sure there are pros and cons to this but atleast with me, so far, the cons seem to outweigh the pros. I miss being able to whip up an API endpoint on the fly. Graphql backend coding reminds me of the days of SOAP with the WSDL and all, I recall it made me hate coding. I was thrilled to see REST get popularized and get away from SOAP completely. Now it seems we are back in a quasi-SOAP world again with Graphql. I'm sure it's a bit more improved now but once being burned I just don't feel comfortable going back to anything that resembles it. I generally like simple and quick solutions that addresses problems. But Graphql seems like it's in the other spectrum of it. On the bright side, Graphql is somewhat fun. :)