Connecting to the API

How to use the GraphQL Playground client to connect to the BaseCMS GraphQL API.

Overview

For a high-level overview of GraphQL and connection information, review the Getting Started section.

In this guide, we'll be using the GraphQL Playground client. You can feel free to use any API client but we think the GraphQL Playground has the best native autocompletion and schema visibility. Other commonly used clients are Insomnia, Altair, or Postman.

You'll need the following information to query the API:

• An API URL

• A Tenant Key

If you're missing any of this information, please reach out to [email protected] and we'd be happy to provide it!

To get started, open the GraphQL Playground client and select New Workspace. Select the option to use a URL endpoint, and input your API URL:

Creating a new workspace in the GraphQL Playground client

Once you click open, your workspace will open up. Before you can make any queries against the API, you need to identify your tenant. To do so, add the x-tenant-key header to your client's configuration. In the GraphQL Playground, you can add that to the "HTTP Headers" tab:

Setting the tenant key header and a basic "ping" query.

Now that you've configured your API client, you can use a feature of GraphQL called introspection. Introspection allows you to browse the schema from your client, without access to the underlying codebase. To browse the schema, you can use the "Schema" (Raw output) or "Docs" (searchable, with comments) tabs on the right side of the screen.

Authenticating to the API

For a high-level overview of the authentication process, review the Modifying data: Introduction guide.

In order to modify data via the GraphQL API, you must be authenticated with a valid user token. To obtain this token, send a request to the login mutation, supplying your BASE username and password.

The `login` mutation response after supplying a username and password.

The returned token should be presented via the Authentication header with a Bearer prefix.

The `activeUser` query when supplied a valid authentication token.

Specifying your BASE instance

In order to use certain mutations that modify data, you will need to specify your BASE instance URL. You can do so by including the URL in the x-base4-api-uri HTTP header.

Including the BASE instance URI header in GraphQL Playground.