A primer on GraphQL

What is GraphQL?

GraphQL is a query language for APIs. It lets you send a query describing the data you want, and the server returns exactly that data.

Compared with a REST API, this gives you:

• A response that matches your query. You ask for the fields you need and get them back in the same shape, without any unnecessary data.
• One request instead of many. You fetch related data in a single query. No need to perform multiple API calls to stitch data together.
• A strongly typed schema. The schema defines every operation the API supports, so you can validate a query (both syntactically and within the GraphQL type system) before execution. This also enables code generation.

Here is a GraphQL query that retrieves a signature order and its signatories:

{
  signatureOrder(id: "abcd") {
    status
    signatories {
      status
      href
    }
  }
}

And the response:

{
  "signatureOrder": {
    "status": "OPEN",
    "signatories": [
      {
        "status": "SIGNED",
        "href": "https://example.com/..."
      },
      {
        "status": "REJECTED",
        "href": "https://example.com/..."
      },
      {
        "status": "OPEN",
        "href": "https://example.com/..."
      }
    ]
  }
}

Using the Idura GraphQL API

Send each query as a POST request to https://signatures.idura.app/v1/graphql. The JSON body takes two parameters: query and, optionally, variables.

You need API credentials to execute queries. Create your application to get them.

curl -X POST -H "Content-Type: application/json" \
  -u clientId:clientSecret \
  --data '{"query": "query ($id: ID!) { signatureOrder(id: $id) { signatories { status } } }", "variables": {"id": "abcd"}}' \
  https://signatures.idura.app/v1/graphql