Getting Started
Get started using the DataHub GraphQL API.
Introduction to GraphQL
The GraphQL community provides many freely available resources for learning about GraphQL. We recommend starting with Introduction to GraphQL, which will introduce you to key concepts like Queries, Mutations, Variables, Schemas & more.
We'll reiterate a few important points before proceeding:
- GraphQL Operations are exposed via a single service endpoint, in the case of DataHub located at
/api/graphql
. This will be described in more detail below. - GraphQL supports reads using a top-level Query object, and writes using a top-level Mutation object.
- GraphQL supports schema introspection, wherein clients can query for details about the GraphQL schema itself.
Setup
The first thing you'll need to use the GraphQL API is a deployed instance of DataHub with some metadata ingested. Unsure how to do that? Check out the Deployment Quickstart.
Querying the GraphQL API
DataHub's GraphQL endpoint is served at the path /api/graphql
, e.g. https://my-company.datahub.com/api/graphql
.
There are a few options when it comes to querying the GraphQL endpoint.
For Testing, we recommend Postman, GraphQL Explorer (described below), or CURL. For Production, we recommend a GraphQL Client SDK for the language of your choice, or a basic HTTP client.
Authentication + Authorization
In general, you'll need to provide an Access Token when querying the GraphQL by
providing an Authorization
header containing a Bearer
token. The header should take the following format:
Authorization: Bearer <access-token>
Authorization for actions exposed by the GraphQL endpoint will be performed based on the actor making the request. For Personal Access Tokens, the token will carry the user's privileges.
Notice: The DataHub GraphQL endpoint only supports POST requests at this time.
On the Horizon
- Service Tokens: In the near future, the DataHub team intends to introduce service users, which will provide a way to generate and use API access tokens when querying both the Frontend Proxy Server and the Metadata Service. If you're interested in contributing, please reach out on our Slack.
- DataHub Client SDKs: Libraries wrapping the DataHub GraphQL API on a per-language basis (based on community demand).
GraphQL Explorer
DataHub provides a browser-based GraphQL Explorer Tool (GraphiQL) for live interaction with the GraphQL API. This tool is available at the path /api/graphiql
(e.g. https://my-company.datahub.com/api/graphiql
)
This interface allows you to easily craft queries and mutations against real metadata stored in your live DataHub deployment. For a detailed usage guide,
check out How to use GraphiQL.
Where to go from here
Once you've gotten the API deployed and responding, proceed to Working with Metadata Entities to learn how to read and write the Entities on your Metadata Graph. If you're interested in administrative actions considering have a look at Token Management to learn how to generate, list & revoke access tokens for programmatic use in DataHub.
Feedback, Feature Requests, & Support
Visit our Slack channel to ask questions, tell us what we can do better, & make requests for what you'd like to see in the future. Or just stop by to say 'Hi'.