Understand GraphQL
#
IntroductionThe Wino's GraphQL API was built with GraphQL. If you're not familiar with this kind of APIs, it's recommended to make some research about GraphQL before.
First of all, a little introduction to this technology. What is GraphQL?
GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data. — graphql.org
Unlike REST APIs, which expose a different endpoint for each resource object, a GraphQL API makes all data available at a single endpoint /graphql
. A client specifies exactly the data that it wants, and the server responds with only that data.
The following example shows a simple GraphQL query and the JSON response:
REQUEST /graphql
RESPONSE /graphql
You can try it now on our Playground (soon). Or in any other third platform.
#
Benefits of using GraphQLGraphQL's declarative approach to data fetching provides significant performance and quality-of-life improvements over a REST API:
- Everything is typed and part of a schema
- Data fetching is declarative and efficient
- Everything is available from a single endpoint
- Documentation is a first-class citizen
#
Make queriesThe schema's entry-point for queries. This acts as the public, top-level API from which all queries must start. In this API, it is possible to search for one instance or an array of instances of any schema.
#
Request a single record from a collectionTo retrieve an item, you must add its unique identifier ID!
to the query variables. Here is an example of retrieving a Node
from the Product
collection:
REQUEST /graphql
- GraphQL
- JavaScript
- PHP
RESPONSE /graphql
To know the fields associated with a particular collection, for example Product
, you can refer to GraphQL Reference.
#
Request a complete collectionTo retrieve the elements of a collection, you must use the Connection pattern as follows:
REQUEST /graphql
- GraphQL
- JavaScript
- PHP
RESPONSE /graphql
By default, a maximum of 20
nodes can be retrieved per request. If you want to retrieve more items from a collection, you can use the first
argument as described in the Connection
type. To manage pagination, you can refer to the dedicated guide Paginate data.
#
Accessing resources layers in a single requestThis query requests informations about others relationships in a single request: VariantPrice
, Category
, Variant
, Tax
etc. with the exact data you want.
REQUEST /graphql
- GraphQL
- JavaScript
- PHP
RESPONSE /graphql
The way GraphQL works will be detailed in the other documentation guides.
#
MutationThe root Mutation
type in a GraphQL schema defines all the write operations that can change data. It is analogous to performing HTTP verbs such as POST
, PATCH
, and DELETE
.
Mutations can take arguments as input similar to the body of a POST
request in REST. Like GraphQL queries, mutations can also return fields. This can be useful for fetching the new state of an object after an update.
#
PlaygroundThe Playground is a way for you to interact with the Wino API. This will allow you to very easily test and understand the database entries through integrated documentation and auto-completion.
More information about the Playground can be found here .
#
External ressourcesIf you wish to have more precision on the use of a GraphQL API, you can refer to the guide proposed by Github "Forming Calls with GraphQL".