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. The $ symbol prefixes variables and is defined in the operation signature.

For example:

query GetSignatureData($datasetId: ID!, $branchId: ID!, $signatureId: String!) {
  getSignatureData(datasetId: $datasetId, branchId: $branchId, signatureId: $signatureId) {
    datasetId
    branchId
    signatureId
    timestampIso8601
  }
}

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!, $modifiedSince: String) {
  getDatasetContent(datasetId: $datasetId, modifiedSince: $modifiedSince) {
    currentMetadata {
      id
      datasetName
      datasetColumns {
        id
        columnName
        valueType
      }
    }
    signedData {
      datasetId
      branchId
      signatureId
      timestampIso8601
      signerEmail
      signedDataJson
      revokedTimestampIso8601
      revokedByEmail
    }
  }
}

Getting a List of Recent Signed Data Events Across Datasets

This query retrieves publication events between the provided timestamps:

query RecentPublicationEvents($startTimestamp: String!, $endTimestamp: String!) {
  recentPublicationEvents(startTimestamp: $startTimestamp, endTimestamp: $endTimestamp) {
    datasetId
    branchId
    signatureId
    timestampIso8601
    signerEmail
    signedDataJson
    revokedTimestampIso8601
    revokedByEmail
  }
}

Getting Eligible Dataset Metadata

First list the dataset IDs eligible for your integration:

query ListEligibleDatasetIds {
  listEligibleDatasetIds
}

getDatasetMetadata accepts those IDs as the datasetIds argument:

query GetDatasetMetadata($datasetIds: [ID!]!) {
  getDatasetMetadata(datasetIds: $datasetIds) {
    id
    datasetName
    datasetColumns {
      id
      columnName
      valueType
    }
  }
}

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