Overview - Why GraphQL?
This API language appeared in the community in 2015 (big thanks to Facebook developers!) and quickly became an interesting alternative to REST or x-rpc.
GraphQL has several advantages:
- Strongly-typed. This permits a robust API contract between Swan and its consumers. Clients can easily generate the code that will allow them to consume our API, and can easily test that their integration went smoothly (aka. Contract testing).
- Resilience. By giving power back to API clients, GraphQL has created a new class of APIs that is especially resilient to evolution.
- Finer command. This remarkable request capacity gives API clients much finer command over the data they wish to fetch or over the way they wish to batch their requests. The freedom Swan's clients have to consume APIs will also be a fantastic opportunity to analyze client behaviour and thus better respond to their needs.
- The Introspection System. This system allows us to ask our server about which queries the API supports. A new developer can easily refer to it as built-in documentation. Having rendered the GraphQL language very introspective from the beginning, its creators helped create a powerful community. Apollo and The Guild come to mind.
- Future-oriented. Ultimately, GraphQL is forward-thinking. In the Golden Age of APIs, when everything seems to come from APIs, GraphQL lets us create meta-graphs consolidating multiple different suppliers (ex. onegraph.com).With a stable and sustainable future, we are convinced GraphQL is the future of APIs.
New to GraphQL? Before digging into our documentation, we suggest you take a moment to acquaint yourself with GraphQLs basic concepts. You will find a short and sweet intro right here, and if you wish to go deeper, there are many fantastic resources:
There are two forms of GraphQL requests: queries and mutations. Both take inputs.
Queries: These are used to fetch data from the remote API, just like a GET in a REST API.
Mutations: These are used to make a change, just like a PUT or a POST in a REST API.
Each request starts with the keyword
query or mutation, then specifies the field or fields you want to get back in the response.query {
user {
mobilePhoneNumber
}
}
mobilePhoneNumber is the name of the field being requested. It is of Stringtype, so it doesn't have any subfields.Here is what you'll receive back in the response:
{
"data": {
"user": {
"mobilePhoneNumber": "{{YOUR_PHONE_NUMBER}}"
}
}
}
Schema - Everything in a GraphQL API is strongly typed: queries, mutations, as well as their inputs and payloads - this makes schemas possible
A schema defines and documents all types available in the API.
Consult a query or mutation's schema to find out if it is allowed in a GraphQL API, and discover what it does and what it returns.
Use introspection queries to get information about the API; you can create a GraphQL query that tells you everything about the schema.
This query will return every single type in the schema:
query {
__schema {
types {
name
description
}
}
}
With schemas, you can validate the exact composition of your requests, and know in advance exactly what you'll get back.
The schema is always up-to-date and is your main point of reference as you integrate with Swan.
For security reasons and in order to keep optimal performance, we implemented some limitations:
- the number of nested fields is limited to 10
- the number of fields are limited to 1000 per query
- the number of root fields are limited to 3
Last modified 7mo ago