Getting started

Authentication

Warpgate API uses API keys to authenticate requests. You can generate your API keys in your Warpgate Dashboard. Whenever you make a GraphQL query to Warpgate, we look for Authorization: Bearer ${API_TOKEN} in the header.

Do not embed your API keys in your Github repository, or in client-side code, etc. it's best to put your Warpgate API keys as an environment variable.

Your API keys grant you access to all GraphQL queries and mutations of your data in Warpgate. So make make sure you keep your API keys secure.

Schema Introspection

To see the full capabilities of Warpgate API, you can head over to its GraphQL interactive playground.

There you will be able to view the different types of objects you can query or mutate.

Querying

Warpgate uses standard GraphQL and has no SDK that is required to be installed in your codebase. To get started right away, here is a utility function that you can copy and paste to your codebase.

./util/warpgateQuery.js

const API_KEY = process.env.WARPGATE_API_KEY

function mapErrors(errors) {
  return errors && errors.reduce((obj, error) => {
    const [key, message] = error.message.split(': ')
    return { ...obj, [key]: message }
  }, {})
}

export default async function warpgateQuery(query, variables) {
  const res = await fetch('https://graph.warpgate.tech/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({ query, variables })
  })

  const { data, errors } = await res.json()

  return { data, errors: mapErrors(errors) }
}

NOTE: include your WARPGATE_API_KEY in your environment variables.

If you're using Next.js, here's an example on how you would use it in your /api/register.js file.

import warpgateQuery from "../../util/warpgateQuery"

const REGISTER = `
  mutation Register($input: RegisterInput!) {
    tenant {
      register(input: $input) {
        id
        email
        username
        insertedAt
        updatedAt
      }
    }
  }
`

export default async ({ body }, res) => {
  const { data, errors } = await warpgateQuery(REGISTER, {
    input: {
      email: body.email,
      username: body.username,
      password: body.password,
    }
  })

  if (errors) {
    res.status(400).json(errors)
  } else {
    res.status(200).json(data)
  }
}

Error handling from Mutations

If you're building a React.js application, you most probably want to display the errors on the client side easily.

In Warpgate, whenever a mutation has validation errors, it will return an error message that lets you identify the fields that need to be corrected.

Let's take a look at this example response for an invalid user login:

{
  "data": {
    "tenant": {
      "login": null
    }
  },
  "errors": [
    {
      "locations": [{ "column": 5, "line": 3 }],
      "message": "username: does not exist",
      "path": []
    }
  ]
}

In the warpgateQuery.js utility code above, it will automatically map the error array values into an object. This makes it easy to easily check which fields need to be highlighted in the front-end.

E.g. errors.username, errors.password, etc.

Nested Queries

The benefit of using GraphQL is nested queries. This lets developers have the freedom to define which fields they exactly need without doing two or more HTTP requests to the server.

Not only is this bandwidth efficient, but it also enables you to avoid having to do n+1 queries.

Example, if you're fetching user data along with other associated data such as their user profile and wallet balances:

query GetUser($userId: ID!) {
  tenant {
    user(userId: $userId) {
      id
      email
      username
      
      profile {
        id
        firstName
        lastName
        photoUrl
      }
      
      wallets {
        id
        name
        currency
        balance
      }
    }
  }
}

Will return a payload response like this:

{
  "data": {
    "tenant": {
      "user": {
        "email": null,
        "id": "1",
        "profile": {
          "firstName": "Johnny",
          "id": "2",
          "lastName": "Silverhand",
          "photoUrl": null
        },
        "username": "[e-mail]",
        "wallets": [
          {
            "balance": "80",
            "currency": "BTC",
            "id": "1",
            "name": "wallet"
          }
        ]
      }
    }
  }
}