GraphQL Schema and Introduction to GraphQL

← Back to Documentation Home

What is GraphQL?

GraphQL is a query language for APIs and a runtime for executing those queries, developed by Facebook in 2012 and open-sourced in 2015. It was created to address the limitations of traditional REST APIs, particularly the problems of over-fetching and under-fetching data. GraphQL enables clients to request exactly the data they need in a single request, making APIs more efficient, flexible, and easier to evolve over time.

GraphQL Queries

A query in GraphQL is how you request data from the server. Unlike REST endpoints where the server determines what data is returned, GraphQL queries let you specify exactly which fields you want. Queries are structured to mirror the shape of the data you’ll receive back.

Variables

Variables in GraphQL allow you to parameterize your queries, making them reusable and more secure. Instead of interpolating values directly into your query string, you declare variables with a type and pass their values separately. Variables are prefixed with a $ symbol and defined in the operation signature.

For example:

query GetDataset($datasetId: ID!) {
  dataset(id: $datasetId) {
    name
    columns
  }
}

Fathom GraphQL Schema

Below is the GraphQL schema for the Fathom Integrations API:

type Column {
  id: ID!
  columnName: String!
  valueType: ValueType!
}

type DatasetAuditTrail {
  currentMetadata: DatasetMetadata!
  signedData: [SignedData!]!
}

type DatasetMetadata {
  id: ID!
  datasetName: String!
  datasetColumns: [Column!]!
}

type Query {
  recentPublicationEvents(startTimestamp: String!, endTimestamp: String!): [SignedData!]!
  listEligibleDatasetIds: [ID!]!
  getDatasetMetadata(datasetIds: [ID!]!): [DatasetMetadata!]!
  getSignatureData(datasetId: ID!, branchId: ID!, signatureId: String!): [SignedData!]!
  getDatasetContent(datasetId: ID!, modifiedSince: String): DatasetAuditTrail!
}

type SignedData {
  branchId: ID!
  datasetId: ID!
  signatureId: String!
  timestampIso8601: String!
  signerEmail: String!
  signedDataJson: String!
  revokedTimestampIso8601: String
  revokedByEmail: String
}

enum ValueType {
  DATE
  DATETIME
  NUMBER
  INTEGER
  STRING
}

Example Queries

Getting Publication History for A Fathom Dataset

This query retrieves the full audit trail for a given dataset id, including signer details, timestamp, and the published dataset:

query DatasetAuditTrail($datasetId: ID!) {
    getDatasetAuditTrail(datasetId: $datasetId) {
        signedData {
            datasetId
            branchId
            signatureId
            timestampIso8601
            signerEmail
            signedDataJson
            revokedTimestampIso8601
        }
      }
    }

Getting a List of Recent Signed Data Events Across Datasets

This query retrieves recent publication events from the last N days:

query RecentEvents($days: Int!) {
  recentPublicationEvents(lastNDays: $days) {
    __typename
    id
    signerEmail
    signatureId
    datasetId
    branchId
    timestampIso8601
  }
}

For more information about the Fathom API, see the API Release Notes.