|
| 1 | +--- |
| 2 | +title: GraphQL |
| 3 | +disableTableOfContents: true |
| 4 | +--- |
| 5 | + |
| 6 | +## What is GraphQL? |
| 7 | + |
| 8 | +GraphQL is a query language for requesting information from an [API](/docs/glossary#api), and a protocol for servers that support it. GraphQL is one of the ways that you can import data into your Gatsby components. |
| 9 | + |
| 10 | +Facebook created GraphQL in 2012 when it realized that it needed an API capable of supporting both web-based and native mobile applications. Facebook released GraphQL with an open source license in 2015. |
| 11 | + |
| 12 | +More traditional APIs use a separate endpoint for each piece or type of data you'd like to request. For example, a newspaper API might contain: |
| 13 | + |
| 14 | +- an `/articles/<id>` endpoint that returns a specific news story; |
| 15 | +- a `/reporters/<id>` endpoint that returns information about a particular reporter. |
| 16 | + |
| 17 | +A single news article page might require two separate network requests: one to retrieve the story data, and another for the reporter's contact details. What's more, the `/reporters` endpoint may return more data than you want to display; it might return their biography and social media accounts, when their name, email, and photo are all that you need for the page. |
| 18 | + |
| 19 | +A GraphQL API, on the other hand, has a single endpoint. To retrieve data, you send one request string that uses a GraphQL-specific syntax. GraphQL executes the functions necessary to retrieve the data that you've requested, and returns a single JSON response. |
| 20 | + |
| 21 | +A request for an article and its reporter might look like the example that follows. |
| 22 | + |
| 23 | +```graphql |
| 24 | +{ |
| 25 | + article(id: '7fdc2787469b') { |
| 26 | + title |
| 27 | + body |
| 28 | + reporter(id: '64669b3f') { |
| 29 | + name |
| 30 | + email |
| 31 | + photo |
| 32 | + } |
| 33 | + } |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +And its response contains only what you've requested. |
| 38 | + |
| 39 | +```json |
| 40 | +{ |
| 41 | + "data": { |
| 42 | + "article": { |
| 43 | + "title": "Gatsby promotes GraphQL adoption", |
| 44 | + "body": "...", |
| 45 | + "reporter": { |
| 46 | + "name": "Jane Gatsby", |
| 47 | + |
| 48 | + "photo": "images/reporters/janegatsby.jpg" |
| 49 | + } |
| 50 | + } |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +You do not have to use GraphQL with Gatsby, however GraphQL offers a few advantages over other methods of importing data. |
| 56 | + |
| 57 | +- You can retrieve only the data that you need for a view. |
| 58 | +- You can add new data types and capabilities without needing to create a new endpoint. |
| 59 | +- You can store content in whatever way makes sense for your site, whether that's in a database, a third-party headless CMS, or Markdown-formatted text files. |
| 60 | + |
| 61 | +## Learn more |
| 62 | + |
| 63 | +- [GraphQL & Gatsby](/docs/graphql/) |
| 64 | + |
| 65 | +- [Why Gatsby Uses GraphQL](/docs/why-gatsby-uses-graphql/) |
| 66 | + |
| 67 | +- [GraphQL](https://graphql.org) official site |
| 68 | + |
| 69 | +- [How to GraphQL](https://www.howtographql.com/) |
0 commit comments