<a href="https://www.cosmicjs.com/knowledge-base/graphql-cms"><img src="https://imgix.cosmicjs.com/4b3277b0-e1aa-11ea-88aa-0bae7ba3a376-graphql-cms.jpg?w=1200 &auto=format" style="width: 100%;" class="fr-fic fr-dib fr-rounded" alt="GraphQL CMS"></a>Cosmic provides a&nbsp;<a href="https://www.cosmicjs.com/knowledge-base/graphql-cms">GraphQL Headless CMS API</a>&nbsp;to power content for your websites and apps.The lack of standardization for APIs has been a challenge that software developers have faced for a long time.&nbsp;A&nbsp;<a href="https://smartbear.com/resources/ebooks/the-state-of-api-2019-report/" rel="noopener noreferrer" target="_blank">study by SmartBear</a>&nbsp;found that 35% of API providers feel their documentation is poor or needs improvement. The problem is that inconsistent APIs increase the learning curve for developers and can slow development velocity. But perhaps poor API documentation is not entirely the fault of those doing the writing.&nbsp;GraphQL aims to solve the difficulties of API standardization and documentation with its straightforward querying language, technology-agnostic backend support, and self-documenting schema system. That&rsquo;s why many development teams are opting for GraphQL over other API technologies that have a lack of widely-used industry standards.<img src="https://cdn.cosmicjs.com/b704d970-e190-11ea-88aa-0bae7ba3a376-graohql-trends.png" style="width: 601px;" class="fr-fic fr-dib"> While REST and GraphQL are both API paradigms that enable the sharing of data over the internet, there are some key differences developers should be aware of. Let&rsquo;s take a deep-dive into GraphQL and whether it&rsquo;s right for your project.<h2> Getting to Grips with GraphQL? Here&rsquo;s What You&rsquo;ll Find in This Article:</h2><ol><li style="font-weight: 400;"><a href="#what-is-graphql">What is GraphQL?</a></li><li style="font-weight: 400;"><a href="#graphql-vs-rest">GraphQL vs REST</a></li><li style="font-weight: 400;"><a href="#exploring-graphql-benefits">Exploring Some GraphQL Benefits</a></li><li style="font-weight: 400;"><a href="#3-graphql-examples">3 GraphQL Examples: What is Graphql Used For?</a></li><li style="font-weight: 400;"><a href="#is-graphql-right-for-your-project">Is GraphQL Right For Your Project?</a></li></ol><h2 id="what-is-graphql"> What is GraphQL?</h2><img src="https://cdn.cosmicjs.com/a60bc2e0-e1aa-11ea-88aa-0bae7ba3a376-GraphQL.png" style="width: 200px; float: right; margin: 10px 0 10px 20px;" class="fr-fir fr-dii"><a href="https://graphql.org/">GraphQL</a> is an API querying language that is both language and database agnostic. That means developers can make standardized data queries to a GraphQL service without any knowledge of the backend implementation. Developers describe the data they need, and the API handles the task of fetching the appropriate data behind the scenes.But let&rsquo;s take a step back and examine the origins of GraphQL.&nbsp;In 2012, GraphQL began as an internal Facebook project led by co-creators Lee Byron, Nick Schrock, and Dan Schafer. Their aim was to
<a href="https://nordicapis.com/interview-with-graphql-co-creator-lee-byron/" rel="noopener noreferrer" target="_blank">build a better Facebook News Feed API</a>:<blockquote>&ldquo;The three of us got to work trying to figure out how to build a better News Feed API and we just got super far down the rabbit hole,&rdquo; Byron told Nordic APIs. &ldquo;I think just a month or two of iterative improvements on what started as a prototype enfolding all of our ideas ended up being the first version of GraphQL.&rdquo;</blockquote>In 2015, Facebook publicly released GraphQL, and in 2018, the GraphQL project was moved from Facebook to the GraphQL Foundation, hosted by the Linux Foundation, a non-profit company.Beyond the standardized querying language, GraphQL is a server-side runtime and type system. On the backend, a GraphQL service needs to be set up to validate and execute queries. This requires a schema that defines the object types and fields available and resolvers which handle the implementation details for retrieving the data on the backend.<h2 id="graphql-vs-rest"> GraphQL vs REST</h2>GraphQL&mdash;similar to REST APIs&mdash;leverages HTTP to send and receive data. The key difference is that different REST requests are created based on HTTP methods and endpoints, while GraphQL queries are shaped within the JSON body of the request. <img data-action="zoom" src="https://cdn.cosmicjs.com/49254280-e26e-11ea-ad85-b3e5c5f45697-cosmic-graphql-cms.png" style="width: 100%;" class="fr-fic fr-dib" alt="Cosmic GraphQL API">Cosmic <a href="https://docs.cosmicjs.com/graphql-api/" rel="noopener noreferrer" target="_blank">GraphQL API</a>. Click to zoom.GraphQL Request For example, take the body of this GraphQL request:<pre>{
 person {
 firstName
 lastName
 }
}</pre>With GraphQL, developers can define which data they want to get returned (first name and last name) by specifying each field within the object (person). The resulting response would look like this:<pre dir="ltr">{
 &quot;data&quot;: {
 &quot;person&quot;: {
 &quot;firstName&quot;: &quot;John&quot;,
 &quot;lastName&quot;: &quot;Smith&quot;
 }
  }
}</pre>This results in another benefit that GraphQL has over REST is the ability to retrieve multiple resources through a single query, whereas REST requires a new query to be made for each resource.The GraphQL response generally has the same structure as the request. Queries are interactive, so any changes to fields in the request body will dynamically change the response as well.REST Request This differs from REST APIs, which are based on resources. For example, here&rsquo;s a similar request to a REST endpoint:<pre dir="ltr">GET https://sample.com/person/1</pre>In the case of REST, developers need to specify the location of the resource on the backend using the correct endpoint (/person) and path parameters (/1). The request body is blank because REST endpoints typically return all the data fields a resource contains.The resulting JSON body could look something like this:<pre>{
 &quot;firstName&quot;: &quot;John&quot;,
 &quot;middleName&quot;: &quot;Andrew&quot;,
  &quot;lastName&quot;: &quot;Smith&quot;,
 &quot;email&quot;: &quot;jas1992@gmail.com&quot;,
 &quot;relationshipStatus&quot;: &quot;single&quot;
}</pre>As you can see, REST APIs are much less flexible, and frontend developers have little control over the response they get back. The REST server returns what backend developers have decided the endpoint should give as a response.<h2 id="exploring-graphql-benefits"> Exploring Some GraphQL Benefits</h2>If you&rsquo;re still asking,&nbsp;&ldquo;why use graphql over REST?&rdquo;, read on. 
 There are a number of areas where GraphQL has the upper hand over most REST services.Standardization: For one, GraphQL is simple to use. There&rsquo;s no industry standard for REST APIs, so developers are forced to sift through documentation to understand any new API they need to use. With GraphQL, however, developers only need to learn the standardized querying language once, and they can work with any application or software that supports the technology.Declarative: In addition, the ability to control the response from an API request enables developers to avoid over fetching or under fetching data. These situations waste bandwidth by providing more information than necessary or requiring multiple API calls to get all the data needed. GraphQL enables developers to pull all the required fields across multiple objects within a single request.Self-documenting: Finally, GraphQL is introspective. That means the API is self-documenting and predictable for developers to use. Since the GraphQL server requires a pre-defined schema, developers can easily explore the data available using manual queries or a tool like&nbsp;
<a href="https://github.com/graphql/graphiql" rel="noopener noreferrer" target="_blank">GraphiQL</a>. With REST endpoints, it&rsquo;s up to the backend developers to document any changes they make or leverage a tool like
<a href="https://swagger.io/" rel="noopener noreferrer" target="_blank">Swagger</a>&nbsp;to generate the API documentation automatically.<h2 id="3-graphql-examples"> 3 GraphQL Examples: What is GraphQL Used For?</h2>With the benefits of GraphQL clear, let&rsquo;s look at some examples of several types of GraphQL queries.&nbsp;<h3>Pulling Data</h3>When developers need to pull data from the backend, it&rsquo;s typically called a GET request in REST terms. With GraphQL, these are queries that look like this:<pre dir="ltr">query GetTitles {
 allBooks {
 books {
 # retrieves title of all books
    title
 } 
  }
}</pre>GraphQL queries can be anonymous or named (GetTitles), and comments can be included using the # character. These features, and many others, helps to clarify what the query&rsquo;s expected response should be.&nbsp;In this case, the response would be similar to this:<pre dir="ltr">{
 &quot;data&quot;: {
  &quot;allBooks&quot;: [
 {
 &quot;title&quot;: &quot;The Martian&quot;
      },
      {
 &quot;title&quot;: &quot;The Great Gatsby&quot;
 }
    ]
  }
}</pre><h3>Editing Data</h3>If developers need to add, modify, or delete data, they&rsquo;ll send a POST, PUT/PATCH, or DELETE request to a REST endpoint. With GraphQL, however, modifying data requires a mutation request. Here&rsquo;s an example of creating a mutation:<pre dir="ltr">mutation createBook(title: &quot;The Old Man and the Sea&quot;, author: &quot;Ernest Hemingway&quot;) { }</pre>This simple mutation will create a new book object on the backend with the specified title and author. If the mutation was successful, we&rsquo;d get a response that includes a unique identifier for the new data object created on the backend.<pre dir="ltr">{ &quot;data&quot;: { &quot;createBook&quot;: &quot;sqdYsdf&quot; } }</pre>As with queries, developers can shape the responses they get from mutations. For example, it&rsquo;s possible to request certain fields to be included in the response along with the unique identifier, such as the title, author, or date created.<h3>Subscriptions</h3>Along with simple queries and mutations, GraphQL supports&nbsp;<a href="https://graphql.org/learn/queries/#operation-name" rel="noopener noreferrer" target="_blank">subscriptions</a>
, which enable a frontend app to retrieve real-time data updates from the server.&nbsp;For example, if a frontend app needed to keep a running list of books as they&rsquo;re added to its database, developers could set up a subscription event using the following request:<pre dir="ltr">subscription {
 new_books {
 id
 title
 author
 date_added
 }
}</pre>Once the subscription is set up, the server will automatically push new data to the frontend. The responses will include all the fields in the initial subscription request.&nbsp;It&rsquo;s important to note that subscriptions are sent to a websocket endpoint because HTTP connections typically close once a response is returned. Instead, the websocket connection, and in turn, subscription remains open until the frontend requests to unsubscribe or an error occurs.&nbsp;Without subscriptions, it&rsquo;s incredibly difficult to build real-time functionality. It often requires an approach called polling, which involves sending periodic requests to an API. But this approach is inefficient and could risk hitting request limits. Subscriptions, therefore, are a powerful way to ensure frontend applications receive data updates in real-time without requiring polling.<h2 id="is-graphql-right-for-your-project"> Is GraphQL Right For Your Project?</h2>While GraphQL adoption is growing, many development teams still opt for REST APIs when integrating new frontends with their CMS because it&rsquo;s an API paradigm they&rsquo;ve been familiar with for a while. GraphQL, however, is ideal for simplifying development, reducing bandwidth usage, and reducing the time-to-market for content-driven apps. In the end, either technology can fuel static site generators, mobile apps, websites, and more.The good news is that with&nbsp;Cosmic&nbsp;you don&rsquo;t need to choose between&nbsp;<a href="https://docs.cosmicjs.com/rest-api/" rel="noopener noreferrer" target="_blank">REST</a>&nbsp;and&nbsp;<a href="https://docs.cosmicjs.com/graphql-api/" rel="noopener noreferrer" target="_blank">GraphQL</a>
. The&nbsp;<a href="https://www.cosmicjs.com/headless-cms">headless CMS</a>&nbsp;supports both technologies, so brands can launch content-rich apps faster, without worrying about backend compatibility. And if you&#39;re not quite ready to make the change to GraphQL, Cosmic&rsquo;s REST API also supports a GraphQL-like feature that allows you to declare what properties are returned with the response using&nbsp;
<a href="https://www.cosmicjs.com/changelog/customize-rest-api-response-object-metafields-search">&quot;props&quot;</a>.Consider Cosmic to fuel your digital experiences, and check out our&nbsp;<a href="https://www.cosmicjs.com/apps?languages=GraphQL">GraphQL-driven demos</a>.

Blogs by Kaya Ismail

Start building today