Forming Calls

Authentication

AdSecure authenticates your API requests using your account’s API key. If you do not include your key when making an API request, or use one that is incorrect or outdated, AdSecure returns an error.

Every account is provided with an API key. Some additional ones can be created by contacting your account manager. In our code examples, we include randomly generated API keys. Replace these with your own to see code examples being executed successfully.

You can use the GraphQL API by adding this API key in a HTTP POST request's header as following:

x-api-key: key

The GraphQL endpoint

The GraphQL API has a single endpoint:

https://api.adsecure.com/graphql

The endpoint remains constant no matter what operation you perform.

Communicating with GraphQL

In REST, HTTP verbs determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is POST.

To query GraphQL using cURL, make a POST request with a JSON payload. The payload must contain a string called query:

curl -H 'x-api-key: nhwQ4taIgNciu3xrabY8BMFXAZGyYGtc8r' -d '
{
  "query":"query { viewer { user { name }}}"
}' -X POST https://api.adsecure.com/graphql

And could be represented as following in a GraphQL way:

query {
  viewer {
    user {
      name
    }
  }
}

The resulting response is going to take the following shape, returning in it body the data you've asked for:

{
  "data": {
    "viewer": {
      "user": {
        "name": "Your user's name!"
      }
    }
  }
}

Using cURL is not the only way to communicate with GraphQL, many different programming languages and clients support GraphQL.

About query and mutation operations

The two types of allowed operations in the GraphQL API are queries and mutations. Comparing GraphQL to REST, queries operate like GET requests, while mutations operate like POST/PATCH/DELETE. The mutation name determines which modification is executed.

For information about rate limiting, see - "GraphQL resource limitations".

Queries and mutations share similar forms, with some important differences.

About queries

GraphQL queries return only the data you specify. To form a query, you must specify fields within fields (also known as nested subfields) until you return only scalars.

Queries are structured like this:

query {
  fields
}

About mutations

To form a mutation, you must specify three arguments:

  1. Mutation name. The type of modification you want to perform.
  2. Input object. The data you want to send to the server, composed of input fields. Pass it as an argument to the mutation name.
  3. Payload object. The data you want to return from the server, composed of return fields. Pass it as the body of the mutation name.

Mutations are structured like this:

mutation {
  mutationName(input: {MutationNameInput!}) {
    MutationNamePayload
}

The input object in this example is MutationNameInput, and the payload object is MutationNamePayload.

Discovering the GraphQL API

GraphQL is introspective. This means you can query a GraphQL schema for details about itself.

  • Query __schema to list all types defined in the schema and get details about each:
query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}
  • Query __type to get details about any type:
query {
  __type(name: "Analysis") {
    name
    kind
    description
    fields {
      name
    }
  }
}
← Concepts