API Overview

Swan chose to base its API on the [GraphQL] technology (https://graphql.org/).

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.

About GraphQL

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:

We like Introduction to GraphQL and How to GraphQL.

Basic Concepts

Queries and Mutations

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": "+33612345678"
    }
  }
}

You can play around with this query as well as all others in Swan's API Explorer.

Schema and Types

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.

The API Explorer

Check out the Swan's API schema and try out your queries and mutations with our API explorer.