BaseHub distributes content via a GraphQL API. Anything that can query GraphQL will work to query our API. We serve all GraphQL requests through a single endpoint:
https://api.basehub.com/graphql
To query data from your repository, you’ll need to send an Authorization
header with Bearer <read-token>
as its value. Here are some examples
You can also authenticate in other ways:
Via an
x-basehub-token
header with the token directly (no “Bearer” scheme)Via a
token
query parameter, also with the token directly (not recommended)
By default, the GraphQL API will respond with the default Branch’s head Commit data. In simpler terms, it’ll respond with the data from your latest Commit.
There are ways to get working/draft (non-committed) content, and also getting data from a specific Commit from time ago. Let’s explore how.
Getting Working/Draft Content
You have two ways of getting Working/Draft content:
By passing a
x-basehub-draft
header with “true“ as its valueBy passing a
draft
query parameter with “true“ as its value
You will notice that the API will respond much slower than normal. This is because we don’t cache Draft API requests.
Getting Data from a Specific Commit
You have two ways of getting content from a specific commit:
By passing a
x-basehub-ref
header with the Commit ID as its valueBy passing a
ref
query parameter with the Commit ID as its value
You can get a Commit ID via the Commits Tab (in the Repo Dashboard, in the middle of the header).
API Design
Our API Design is intentionally simple. As you start exploring the GraphQL schema, you’ll notice that it’s closely related to how your sidebar looks like. For the following Tree structure:
- Document Block: Blog
- Text Block: Hero Title
- Collection Block: Blog Posts
- Rich Text Block: Content
- Image Block: Cover Image
- Date Block: Publish Date
- Reference Block: Author
the API will generate a schema like the following (represented in TypeScript :
Explorer/GraphiQL
You’ll be able to explore your GraphQL API in the Explore Panel, available in this route:
https://basehub.com/<team>/<repo>/connect/explore