# The missing Prismic Documentation

For whatever reason, [Prismic](https://prismic.io/) doesn't really make many details public about how their APIs work, instead choosing to obscure this information in a number of libraries.

This approach is no doubt a well-intentioned attempt to make things "simple," but, as anyone who as ever encountered a [leaky-abstraction](https://en.wikipedia.org/wiki/Leaky_abstraction) will tell you, it ends up making things much more difficult. The approach sacrifices the elegance and flexibility of the platform, raises the barrier to entry and is patronizing to competent developers.

However, the product itself is great and I'm already quite committed. So rather than leave, I thought I'd take it upon myself to write the missing Prismic documentation.

# Fetching data via GraphQL

When sending a query to GraphQL endpoint, the following headers are required:

Content-Type: "application-json"
Prismic-Ref: "XXXX"

## What is Prismic-Ref?

In Prismic, a `ref` is a string of characters that represents a reference to a given state of your content.

A reference can point to the current state, a previous state, or a branched state (i.e. a "release") of your content.

## Showing published content

The `ref` of the current published content is called the `master-ref`.

To fetch the master ref, send a GET request to `https://yourapp.cdn.prismic.io/api/v2`. You should get a JSON response back. From this, you can parse the response to get the master `ref`.

Fetching the master ref and using that to query data might look something like this

response = await fetch("https://yourapp.cdn.prismic.io/api/v2")

ref = response.json().refs[0].ref

data = query_graphql(query, ref)

In the `query_graphql` method, set the `Prismic-Ref` header to the value of `ref`.

## Showing preview content

But what if you need to fetch data that isn't in the master ref?

What if you want to fetch data from a preview of a release?

In this case, simply set the value of `Prismic-Ref` to the value of the `io.prismic.preview` cookie. Again, pseudo-code:

ref = COOKIE.get("io.prismic.preview")

data = query_graphql(query, ref)

# Link resolver

This is still a mystery to me. Reach out if you have any clues as to how this is supposed to work?