{"id":246280,"date":"2016-10-13T06:57:16","date_gmt":"2016-10-13T13:57:16","guid":{"rendered":"http:\/\/css-tricks.com\/?p=246280"},"modified":"2017-04-06T16:55:37","modified_gmt":"2017-04-06T23:55:37","slug":"declarative-data-fetching-graphql","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/declarative-data-fetching-graphql\/","title":{"rendered":"Declarative Data Fetching with GraphQL"},"content":{"rendered":"<p><em class=\"explanation\">The following is a guest post by Nilan Marktanner from <a href=\"https:\/\/graph.cool\/\" rel=\"noopener\">Graph.cool<\/a>. I don&#8217;t know about y&#8217;all but I&#8217;ve spent plenty of time in my career dealing with REST API&#8217;s. It&#8217;s a matter of always trying to figure out what URL to hit, what data to expect back, and how you can control that data. A quick glance at GraphQL makes it seem like it simplifies things both for the creators and consumers of the API. Let&#8217;s let Nilan explain.<\/em><\/p>\n<p><!--more--><\/p>\n<p>When it comes to standards for designing the API architecture for web services of all kinds, REST has been the state of the art for many years already. With the widespread popularity of REST, GraphQL&#8217;s claim to replace it as the API bridge between front end and back end has received a lot of scepticism. But GraphQL is already very well established, as evidenced by Facebook&#8217;s <a href=\"http:\/\/graphql.org\/blog\/production-ready\/\" rel=\"noopener\">announcement of GraphQL being production ready<\/a> and GitHub&#8217;s <a href=\"http:\/\/githubengineering.com\/the-github-graphql-api\/\" rel=\"noopener\">reveal of their GitHub GraphQL API<\/a>.<\/p>\n<h3>The Infrastructure Required for GraphQL<\/h3>\n<p>Like with REST, several components are needed before we can use a GraphQL API.<\/p>\n<ul>\n<li><strong>A GraphQL Client<\/strong> &#8211; This allows us to fetch or modify data that is stored in the back end. Plain HTTP requests do a wonderful job if you work on smaller projects, as requests and responses are both encoded in JSON.<\/li>\n<li><strong>A GraphQL Back End<\/strong> &#8211; We have to expose a GraphQL schema that describes our API as a type system. A type system consists of different methods that are called <em>queries<\/em> (to fetch data) and <em>mutations<\/em> (to modify data). Here the real work happens, as we have to implement a mapping between these methods and our data layer. For example, a query <code>allUsers<\/code> to fetch all users might be mapped to a SQL query like <code>SELECT * FROM USERS<\/code>.<\/li>\n<\/ul>\n<p>In this article we will explore a possible GraphQL API for an Instagram clone highlighting some of the benefits that GraphQL brings to the table.<\/p>\n<h3>The GraphQL Schema<\/h3>\n<p>The endpoints of a REST API are often reminiscent of the actual schema of the database. Endpoints like <code>\/users<\/code> or <code>\/posts<\/code> that enable access to the database tables <code>User<\/code> and <code>Post<\/code> are common.<\/p>\n<p>The GraphQL Schema however needs to be built as a type system in a two step process. <\/p>\n<h4>Step 1<\/h4>\n<p>Object types are composed using primitive types like String and Boolean. In our case, we will build the <code>User<\/code> and the <code>Post<\/code> object types described in IDL syntax:<\/p>\n<pre><code>type User {\r\n  id: String!\r\n  name: String\r\n  posts: [Post]\r\n}\r\n\r\ntype Post {\r\n  id: String!\r\n  imageUrl: String\r\n  description: String\r\n  author: User\r\n}<\/code><\/pre>\n<p>We have a <code>User<\/code> object type that consists of the fields <code>name<\/code> of type String and <code>posts<\/code> of list type <code>Post<\/code> (denoted by [Post]) and the <code>Post<\/code> object type that consists of a <code>imageUrl<\/code> and a <code>description<\/code> field of type String and an <code>author<\/code> field of type <code>User<\/code>.<\/p>\n<p>Additionally to the fields mentioned above, both object types have the <code>id<\/code> field which is a required String (denoted by <code>String!<\/code>).<\/p>\n<h4>Step 2<\/h4>\n<p>These types are then used to define actual queries, like the <code>allUsers<\/code> query that can be used to fetch all existing users in the database. You can basically expose whatever you come up with, but most popular are queries to fetch all or one item of a specific type and so called mutations to create, update and delete items of a specific type.<\/p>\n<h3>Tooling<\/h3>\n<p>The type system encoded in the GraphQL schema paves the way for powerful tools like <a href=\"https:\/\/github.com\/graphql\/graphiql\" rel=\"noopener\">GraphiQL<\/a> for example, which is maintained by Facebook. It allows the playful exploration of a GraphQL API.<\/p>\n<figure id=\"post-246283\" class=\"align-none media-246283\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2016\/10\/graphql.gif?ssl=1\" alt=\"\" data-recalc-dims=\"1\" \/><\/figure>\n<p>Features like auto completion (as shown in the gif) and an automatically generated documentation increase developer experience a lot and are usually enough to get started with consuming an GraphQL API. Let&#8217;s now take a closer look at some queries and mutations!<\/p>\n<h3>GraphQL Queries<\/h3>\n<p>Queries in GraphQL are declarative and hierarchical. We&#8217;ll see in a moment what this means exactly, but rapidly changing data requirements in front end applications make this one of GraphQL&#8217;s biggest selling points.<\/p>\n<h4>Query Basics<\/h4>\n<p>Let&#8217;s assume that we are only interested in the <code>id<\/code> and <code>name<\/code> of all our users. Declarative means that we declare precisely what we are interested in:<\/p>\n<pre rel=\"GraphQL\"><code class=\"graphql\">query {\r\n  allUsers {\r\n    id\r\n    name\r\n  }\r\n}<\/code><\/pre>\n<p>The query response contains only fields that we just declared:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"allUsers\": [\r\n      {\r\n        \"id\": \"some-id\",\r\n        \"name\": \"Nilan\"\r\n      },\r\n      {\r\n        \"id\": \"another-id\",\r\n        \"name\": \"Chris\"\r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>We can see that the structure of the query response follows the structure of the query closely. If we want to fetch more data with a query, we just include more fields:<\/p>\n<pre rel=\"GraphQL\"><code class=\"graphql\">query {\r\n  allUsers {\r\n    id\r\n    name\r\n    posts {\r\n      imageUrl\r\n    }\r\n  }\r\n}<\/code><\/pre>\n<p>Here we see what hierarchical means. The query follows the relationship hierarchy of our schema and we can select the fields we are interested in for all the posts as well. The response could be:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"allUsers\": [\r\n      {\r\n        \"id\": \"some-id\",\r\n        \"name\": \"Nilan\",\r\n        \"posts\": [\r\n          {\r\n            \"imageUrl\": \"https:\/\/unsplash.it\/200\/300?image=31\"\r\n          },\r\n          {\r\n            \"imageUrl\": \"https:\/\/unsplash.it\/200\/300?image=38\"\r\n          }\r\n        ]\r\n      },\r\n      {\r\n        \"id\": \"another-id\",\r\n        \"name\": \"Chris\",\r\n        \"posts\": [\r\n          {\r\n            \"imageUrl\": \"https:\/\/unsplash.it\/200\/300?image=99\"\r\n          }\r\n        ]\r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>It&#8217;s also important to note that we just changed the query without touching our GraphQL backend and it still worked! Once we thought of a solid type system and exposed that in our GraphQL schema, we can change queries on the fly in our frontends and our GraphQL server will give back the correct response just like that. That also means no more hassle with multiple endpoints or API versions as is common in REST.<\/p>\n<p>Combining fields hierarchically like we did also reduces the amount of HTTP requests between the frontend and the backend. Fetching a user and all of its friends typically needs at least two requests with REST, while we only needed one.<\/p>\n<h4>Advanced Query Features<\/h4>\n<p>GraphQL queries accept query parameters that are usually used to offer advanced features like filtering or pagination. We won&#8217;t go into depth here, but let&#8217;s see a few quick examples.<\/p>\n<p>Filtering is pretty flexible and powerful. For example we can only show users with the name <code>Chris<\/code>:<\/p>\n<pre rel=\"GraphQL\"><code class=\"graphql\">query {\r\n  allUsers(filter: {name: \"Chris\"}) {\r\n    id\r\n    name\r\n  }\r\n}<\/code><\/pre>\n<p>Unsurprisingly, the query response only contains one user:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"allUsers\": [\r\n      {\r\n        \"id\": \"another-id\",\r\n        \"name\": \"Chris\"\r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>With pagination we can express how many consecutive data items we are interested in. This is especially useful if we want to build a feed with several pages similar to Google search results.<\/p>\n<p>Let&#8217;s only query the first of our users. We can use the <code>first<\/code> argument to accomplish that.<\/p>\n<pre rel=\"GraphQL\"><code class=\"qraphql\">query {\r\n  allUsers(first: 1) {\r\n    id\r\n    name\r\n  }\r\n}<\/code><\/pre>\n<p>And as expected we only get back the first user:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"allUsers\": [\r\n      {\r\n        \"id\": \"some-id\",\r\n        \"name\": \"Nilan\"\r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>Now if we want to query the second user, we can skip the first user and fetch only the next user by combining <code>first<\/code> with <code>skip<\/code>:<\/p>\n<pre rel=\"GraphQL\"><code class=\"graphql\">query {\r\n  allUsers(first: 1, skip: 1) {\r\n    id\r\n    name\r\n  }\r\n}<\/code><\/pre>\n<p>This returns the second user:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"allUsers\": [\r\n      {\r\n        \"id\": \"another-id\",\r\n        \"name\": \"Chris\"\r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>These are only some of the ways we can use query arguments. If we wanted to provide another similar functionality, like sorting the query response by a field, we would have to define a new query argument in the GraphQL schema and implement that feature in the backend accordingly.<\/p>\n<h3>Mutations<\/h3>\n<p>Mutations are the counterpart to queries. While we can fetch data with queries, mutations allow us to create new data or update or delete existing data items. The respective mutations could be called <code>createPost<\/code>, <code>updatePost<\/code> and <code>deletePost<\/code>.<\/p>\n<p>The values for the fields of the new data item are supplied with query arguments. Mutations require the selection of fields that will be returned as a query response as well. A mutation to create a new post could look like this:<\/p>\n<pre rel=\"GraphQL\"><code class=\"graphql\">mutation {\r\n  createPost(imageUrl: \"https:\/\/unsplash.it\/200\/300?image=27\", description: \"#random\", authorId: \"some-id\") {\r\n    id\r\n  }\r\n}<\/code><\/pre>\n<p>The response will contain the newly created <code>id<\/code>:<\/p>\n<pre rel=\"JSON\"><code class=\"language-javascript\">{\r\n  \"data\": {\r\n    \"createPost\": {\r\n      \"id\": \"some-newly-generated-id\"\r\n    }\r\n  }\r\n}<\/code><\/pre>\n<h3>Conclusion<\/h3>\n<p>In this article, we got an overview of GraphQL as an alternative to REST. <\/p>\n<p>We saw that GraphQL clients are needed to connect the front end with the backend and how a GraphQL schema for an  Instagram clone can look like. We learned how we can use queries and mutations to fetch and modify data and the GraphQL API allows us to select exactly the fields we need in a declarative and hierarchical way. With filtering and pagination, we glanced at two powerful concepts while GraphiQL showed off the fantastic possibilities of tools that rely on the defined type system.<\/p>\n<p>If you want to learn more about GraphQL, you should take a look at <a href=\"http:\/\/graphql.org\/learn\/\" rel=\"noopener\">learn section of the GraphQL website<\/a> and <a href=\"http:\/\/learngraphql.com\" rel=\"noopener\">Learn GraphQL<\/a> which are two very accessible resources.<\/p>\n<p><a href=\"https:\/\/facebook.github.io\/relay\/\" rel=\"noopener\">Relay<\/a> and <a href=\"https:\/\/github.com\/apollostack\/apollo-client\" rel=\"noopener\">Apollo Client<\/a> are two popular GraphQL clients for JavaScript. If you are interested in Relay head over to <a href=\"http:\/\/learnrelay.org\/\" rel=\"noopener\">Learn Relay<\/a> for an interactive and comprehensive introduction to Relay.<\/p>\n<p><a href=\"https:\/\/github.com\/graphql\/graphql-js\" rel=\"noopener\">graphql-js<\/a> and <a href=\"https:\/\/github.com\/sangria-graphql\/sangria\" rel=\"noopener\">Sangria<\/a> are two popular libraries to build a GraphQL backend in JavaScript and Scala, respectively.<\/p>\n<p>To get quickly started with GraphQL, you can checkout <a href=\"http:\/\/graph.cool\" rel=\"noopener\">Graphcool<\/a> which allows you to graphically define your models and fields to automatically generate a GraphQL backend and provides additional features like an advanced permission system and file management out of the box.<\/p>\n<figure id=\"post-246284\" class=\"align-none media-246284\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2016\/10\/graphcool-1.gif?ssl=1\" alt=\"\" data-recalc-dims=\"1\" \/><\/figure>\n<figure id=\"post-246285\" class=\"align-none media-246285\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2016\/10\/graphcool-2.gif?ssl=1\" alt=\"\" data-recalc-dims=\"1\" \/><\/figure>\n","protected":false},"excerpt":{"rendered":"<p>The following is a guest post by Nilan Marktanner from Graph.cool. I don&#8217;t know about y&#8217;all but I&#8217;ve spent plenty of time in my career dealing with REST API&#8217;s. It&#8217;s a matter of always trying to figure out what URL to hit, what data to expect back, and how you can control that data. A [&hellip;]<\/p>\n","protected":false},"author":248291,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"c2c_always_allow_admin_comments":false,"footnotes":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":[]},"categories":[4],"tags":[667,871],"jetpack_publicize_connections":[],"acf":[],"jetpack_featured_media_url":"","jetpack-related-posts":[],"featured_media_src_url":null,"_links":{"self":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/246280"}],"collection":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/users\/248291"}],"replies":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/comments?post=246280"}],"version-history":[{"count":4,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/246280\/revisions"}],"predecessor-version":[{"id":246368,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/246280\/revisions\/246368"}],"wp:attachment":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/media?parent=246280"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/categories?post=246280"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/tags?post=246280"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}