{"id":3852,"date":"2019-05-29T01:14:56","date_gmt":"2019-05-29T01:14:56","guid":{"rendered":"https:\/\/www.solutionstreet.com\/blog\/?p=3852"},"modified":"2019-05-29T01:14:56","modified_gmt":"2019-05-29T01:14:56","slug":"you-really-should-be-using-graphql","status":"publish","type":"post","link":"https:\/\/www.solutionstreet.com\/blog\/2019\/05\/29\/you-really-should-be-using-graphql\/","title":{"rendered":"You Really Should Be Using GraphQL"},"content":{"rendered":"\n
\"\"<\/figure><\/div>\n\n\n\n

Origin of GraphQL<\/strong>
<\/p>\n <\/p>\n\n\n\n

Back in 2012, Facebook was dealing with an issue that many of us software developers who build products with multiple front-ends (web and mobile) must address. How can we build a server component Application Programming Interface (API) that works seamlessly with both mobile and web applications? How can we have the same API calls with the same data response easily handled by web and mobile and be performant? The result of Facebook having difficulty with these questions was the creation of GraphQL<\/a> by Facebook with a specification, open source code, and a community. GraphQL not only provides a solution for the different requirements of web and mobile, but also the ever increasing need to have a somewhat generic API access to systems.
<\/p>\n\n\n\n

<\/p>\n\n\n\n \n

GraphQL vs. Rest<\/strong><\/p>\n \n\n\n\n

Many of us have used Representational State Transfer (REST<\/a>) for a while and understand that it\u2019s an architectural style. REST refers to a set of principles like statelessness for developing APIs. It uses HTTP<\/a> verbs\/methods like GET, PUT, POST to link resources to actions.
<\/p>\n\n\n\n

If you take a banking application with an object like a banking transaction you may have the following REST API call (endpoint) which returns the Transaction along with the name of the associated Account (i.e., attributes of its parent).  
<\/p>\n\n\n\n

GET \/transactions\/1234\n{\n \"date\": \"2019-05-12\",\n \"amount\": 100.50,\n \"account\": \n {\n   \"name\": \"My Checking\"\n }\n}\n<\/pre>\n\n\n\n
This object (or resource) is coupled with the way you retrieve it. Here we are retrieving a banking Transaction with the id of \u201c1234\u201d based on the URL pattern and we have defined on the server that when we retrieve the Transaction we will bring along with it the name from the associated Account. We have essentially denormalized a bit of Account data for the call and determined that this would occur on the server.
<\/p>\n\n\n\n
GraphQL is really an extension of REST, but the key difference is that the resource is decoupled from the way you retrieve it. In GraphQL there is the resource AND then there is the action (the example below uses a Query as the action). Here we define the resource and the action separately where Transaction and Account objects are the resources and the Query type defines basic ways you can retrieve the resources:
<\/p>\n\n\n\n
type Transaction {\n id: ID!\n date: Date!\n amount: Float!\n account: Account! \n}\ntype Account {\n id: ID!\n name: String!\n balance: Float!\n transactions: [Transaction!]!\n}\ntype Query {\n  transaction(id: ID!): Transaction\n  account(id: ID!): Account\n}\n<\/pre>\n\n\n\n
\/\/ Note that the exclamation point (!) above represents required – cannot be null<\/em>
<\/p>\n\n\n\n
Then the GraphQL call in basic URL form is as follows:
<\/p>\n\n\n\n
GET \/graphql?query={ transaction(id: \"1234\") { date, amount, account { name } } }\n{\n \"date\": \"2019-05-12\",\n \"amount\": 100.50,\n \"account\": \n {\n   \"name\": \"My Checking\"\n }\n}\n<\/pre>\n\n\n\n
In this very simple case above, we are comparing using a GET method for the specific REST call vs. a generic Query method for the GraphQL call. Using the above GraphQL call we can select which fields we want to retrieve from our client application. Therefore, while we are \u201cstuck\u201d with the REST call returning only the name of the Account since that was determined on the server when we implemented the REST call, we have the flexibility of selecting more fields from the Account (e.g., balance) if we prefer when we execute the call from the client without changing any server code. We can expand this example in many facets by adding or subtracting fields and hierarchical objects we are retrieving. Herein lies the major benefit. We no longer need to establish the returning schema on the server knowing that we may need to handle different front-end clients with different requirements for data including fields and levels of data in a hierarchy.<\/p>\n\n\n\n
 \n
Why GraphQL?<\/strong><\/p>\n <\/p>\n\n\n\n
<\/p>\n\n\n\n
You should already see the major benefit of using GraphQL – its ability to allow the client to define the fields and hierarchies to return without changing the server definition and multiple roundtrips to the server. Those of you who have done many RESTful applications understand that typically you may need three calls to the server before getting the data you need for a single page.
<\/p>\n\n\n\n
In my examples that follow, I will continue with a fictitious banking application in which there are Customers who have one or more Accounts and those Accounts have zero or more Transactions. Note that an Account can have one or more Customers (think joint account) but a Transaction can only belong to a single Account.
<\/p>\n\n\n\n
Figure 1.<\/em>
<\/p>\n\n\n\n
\"\"<\/figure><\/div>\n\n\n\n
Figure 2 shows a mockup of a single web page displaying a Customer\u2019s information along with a list of their Accounts followed by the most recent three Transactions for a selected Account.
<\/p>\n\n\n\n
Figure 2.<\/em><\/p>\n\n\n\n
<\/p>\n\n\n\n
\"\"\/<\/figure><\/div>\n\n\n\n
Using REST we may have situations where we need three or many more calls to the server:<\/p>\n\n\n\n
  1.  \/customers\/1<\/em> – retrieve some information from the customer with id of \u201c1\u201d<\/li>
  2.  \/customers\/1\/accounts<\/em> – retrieve that customer\u2019s accounts<\/li>
  3. \/customers\/1\/accounts\/123\/transactions<\/em> – for each account, retrieve the most recent three transactions<\/li><\/ol>\n\n\n\n
    In GraphQL there is only one API and that API is controlled by the client so the client can make a single call to retrieve all of the required data including the Customer information, the Accounts, and the most recent three Transactions for each Account. In a traditional REST API environment, how would your REST call be implemented for retrieving the most recent three transactions? Would you have a single REST call to perform all of these three by essentially denormalizing your data and creating a non-REST API? What if you had different client access requiring different sets of data? Developers typically work around this problem by creating more and more REST calls to appease the client and over-fetching data.
    <\/p>\n\n\n\n
    The main benefits of GraphQL are:<\/p>\n\n\n\n
    1. Hierarchical – the GraphQL client can request data in a hierarchical form including multiple data items from different parts of a hierarchy with a single call.<\/li>
    2. Strongly Typed – since the GraphQL schema is strongly typed, descriptive error messages can be provided with incorrect client calls.<\/li>
    3. Introspective – a GraphQL server can be queried for its schema\/API.<\/li>
    4. No Versioning – for many traditional RESTful applications, changing the server call to accommodate the client requires a change in the version of the server API and informing the clients. With GraphQL you can add new schema functions without change on the client and you can deprecate other functions but still allow them to function.<\/li><\/ol>\n\n\n\n
      \u201c<\/span>Using GraphQL is a much more dynamic solution to allow client access to data with the freedom to retrieve what is wanted without server changes.<\/em>\u201d<\/span><\/div>\n\n\n\n
       \n
      Tools and Libraries<\/strong><\/p>\n <\/p>\n\n\n\n
      There are a number of tools and libraries available for GraphQL for all stacks. This includes the Java stack, Ruby on Rails, Python\/Django, and of course JavaScript\/NodeJS. I\u2019ve only tackled GraphQL in the JavaScript\/NodeJS stack so far. This website<\/a> that I found provides the clearest view of what libraries exist for each software language at each part of the stack.
      <\/p>\n\n\n\n
      With respect to my example banking application I am using a NodeJS server with graphql-yoga<\/a> library to handle client calls. This package is built upon Express and has a powerful and pleasant web playground to execute actions to the server. In addition, I am using Prisma<\/a> as a data layer to provide a pretty expressive ORM that works with SQL and noSQL databases and handles GraphQL calls with simplicity. This ORM autogenerates (no code is generated, but the functions are there) all of the CRUD processing similar to Rails for those of you who have used Rails. It also provides a type-safe client. 
      <\/p>\n\n\n\n
      Now when I first was using this architecture I was confused a bit, so let me see if I can explain it simply. In this architecture we can have a web or mobile client executing GraphQL calls which calls to our node server running graphql-yoga which then (by using what\u2019s called resolvers), handles authentication, authorization, and any business functionality and uses our Prisma server for data access – i.e., we have client->server->server.  
      <\/p>\n\n\n\n
      Since there is much complexity of a graphql function (i.e., so many different possibilities) having an ORM like Prisma is very useful since all of the permutations are handled for you. Any tool like Prisma has its downsides and I will discuss those later.
      <\/p>\n\n\n\n
      Here is our datamodel.graphql<\/strong> file to define our banking application resources. This file is used by Prisma (our ORM):
      <\/p>\n\n\n\n
      type Customer {\n id: ID! @unique\n firstName: String!\n lastName: String!\n email: String! @unique\n accounts: [Account!]! @relation(name: \"CustomerToAccount\", onDelete: CASCADE)\n}\n\ntype Account {\n id: ID! @unique\n name: String!\n balance: Float!\n owners: [Customer!]! @relation(name: \"CustomerToAccount\", onDelete: CASCADE)\n transactions: [Transaction!]! @relation(name: \"AccountToTransaction\", onDelete: CASCADE)\n}\n\ntype Transaction {\n id: ID! @unique\n date: DateTime!\n amount: Float!\n cleared: Boolean @default(value: \"false\")\n account: Account! @relation(name: \"AccountToTransaction\", onDelete: SET_NULL)\n}\n<\/pre>\n\n\n\n
      Again this is defining a Customer with a many-to-many relationship with Accounts and Accounts having a zero-to-many relationship with Transactions. Prisma will generate the database based on the data model above.
      <\/p>\n\n\n\n
      Here you can see the generated tables in my Postgres database: 
      <\/p>\n\n\n\n
      \"\"\/<\/figure>\n\n\n\n
      Note that even though one of our relationships is a one-to-many it still generates a cross-reference table.
      <\/p>\n\n\n\n
      As mentioned before, GraphQL separates the resource and the actions. Above in our datamodel.graphql<\/strong> file we defined the resources and in GraphQL we also need to define the actions (i.e., the allowable actions by the client). These actions are defined in a schema.graphql<\/strong> file as follows for my examples:
      <\/p>\n\n\n\n
      type Mutation {\n createCustomer(data: CustomerCreateInput!): Customer!\n createAccount(data: AccountCreateInput!): Account!\n createTransaction(data: TransactionCreateInput!): Transaction!\n updateCustomer(data: CustomerUpdateInput!, where: CustomerWhereUniqueInput!): Customer\n updateAccount(data: AccountUpdateInput!, where: AccountWhereUniqueInput!): Account\n updateTransaction(data: TransactionUpdateInput!, where: TransactionWhereUniqueInput!): Transaction\n}\n\ninput CustomerCreateInput {\n firstName: String!\n lastName: String!\n email: String!\n accounts: AccountCreateManyWithoutOwnersInput\n}\n\ntype Query {\n customers(where: CustomerWhereInput, orderBy: CustomerOrderByInput, skip: Int, after: String, before: String, first: Int, last: Int): [Customer]!\n accounts(where: AccountWhereInput, orderBy: AccountOrderByInput, skip: Int, after: String, before: String, first: Int, last: Int): [Account]!\n transactions(where: TransactionWhereInput, orderBy: TransactionOrderByInput, skip: Int, after: String, before: String, first: Int, last: Int): [Transaction]!\n customer(where: CustomerWhereUniqueInput!): Customer\n account(where: AccountWhereUniqueInput!): Account\n transaction(where: TransactionWhereUniqueInput!): Transaction\n}\n\ntype Subscription {\n customer(where: CustomerSubscriptionWhereInput): CustomerSubscriptionPayload\n account(where: AccountSubscriptionWhereInput): AccountSubscriptionPayload\n transaction(where: TransactionSubscriptionWhereInput): TransactionSubscriptionPayload\n}\n<\/pre>\n\n\n\n
      This file above is generated by Prisma and then altered, imported, or reused in part by the GraphQL yoga server to limit what the client can do. Above we can see queries defined along with mutations and subscriptions. You can ignore some of the complexity of the parameters above within the functions, but understand that this is where you are defining your actions along with the data being fed and returned from those actions. Anywhere there is a resource mentioned (i.e., Account), GraphQL automatically allows you to walk up and down that hierarchy.<\/p>\n\n\n\n
       \n
      Setting Up Data for My Examples<\/strong><\/p>\n <\/p>\n\n\n\n
      Typically, with many applications we have relationships in our data ranging from simple to complex. To display and explain certain GraphQL statements in the following sections I\u2019m going to use our fictitious bank data model of a Customer having a many-to-many relationship with Accounts (e.g., two people are joint owners on multiple accounts) and a one-to-many relationship between Accounts and Transactions whereas an Account can have zero or more Transactions. 
      <\/p>\n\n\n\n
      Within GraphQL there are three different execution concepts:<\/p>\n\n\n\n