GraphQL Concepts
To understand the basic concepts of GraphQL, you should refer to the information in this page. If you are already familiar with these concepts, then you can connect to a GraphQL endpoint or go to the example pages.
For more information on GraphQL, you can read the following online resources:
- Tutorials: howtographql
- Specifications:GraphQL spec on github
- Example Documentation Sites: Shopify Yelp and Braintree
Single Endpoint
Using GraphQL, you enter your requests in a single endpoint. A request can be made using any type of operation that is part of the GraphQL schema, thus allowing you to obtain the exact data you need from the database. Conversely with REST, you cannot specify the data you need with the same level of granularity, because data is gathered from multiple endpoints with fixed data structures. Therefore, a REST response is likely to contain unneeded data. With this capability, GraphQL avoids the problem of overfetching and underfetching data.
More information on the single endpoint and fetching data in GraphQL is provided in the GraphQL is the better REST tutorial.
Strong Typing
The GraphQL language is strongly typed which means that the information you enter must be correct for a valid response to be provided. This is because the data is validated against a GraphQL schema. For example, if you enter a description field as a string that is not enclosed in inverted commas, you will receive an error in the response.
Operations
There are two types of operations that exist in GraphQL: queries and mutations. Query operations retrieve data, while mutation operations manipulate data.
Query
You send a query request to a server in order to fetch data that is read-only. A query is akin to a select statement in SQL. A query returns an object to your request via the response. A query operation may appear similar to the following:
{
applicants(quickSearch:"tim"){
applicant {
applicantId
applicantName
applicantSurname
}
}
}
At the top -level, a query operation includes a root field, which has specific information that you need from the server. In the above example, the field is called applicants that is enclosed in curly brackets.
There are also fields that determine the format of the response. These fields are called the selection and, in this example, include theapplicantapplicantID, applicantName, and applicantSurname fields. Without the selection, the server does not know how to structure the data in the response. The fields must be enclosed in curly brackets. A selection is also known as a payload.
A field may contain one or more arguments within brackets which alter the behaviour of the field. In this above example, the argument is quicksearch, which is placed after the applicants root field. This means that the applicants that are returned must be from a specific search condition where there is the text string "tim". The different types of arguments are described in the examples section of the guide.
Mutation
A mutation allows you to write to the data in the form of an insert, update, or delete action. Once specified in a request, the inserted or updated data is then fetched from the server in the response.
A mutation operation may appear similar to this:
mutation {
insertWorkHistory (input:{clientID: 41, company: "IBM",})
{
clientID
company
placementID
}
}
A mutation operation also combines a root field with optional arguments, and a selection. A mutation operation must contain the keyword "mutation" before the root field. But for a query operation, the keyword "query" is optional.