Skip to main content

Introduction to GraphQL

This guide introduces GraphQL for developers who are familiar with REST APIs but new to GraphQL. If you've already worked with GraphQL, skip ahead to Authentication or Your First Query.

What is GraphQL?​

GraphQL is a query language for APIs. Instead of calling many different REST endpoints to assemble the data you need, you send a single request to one endpoint and specify exactly which fields you want back.

The Certificate Manager GraphQL endpoint:

POST https://api.venafi.cloud/graphql

Every request — whether you're reading data or making changes — goes to this single URL.

How GraphQL Differs from REST​

RESTGraphQL
EndpointsOne URL per resource (/certificates, /certificates/{id}, /cloud-providers)One URL for everything (/graphql)
Data shapeServer decides what fields to returnYou specify exactly which fields you want
Related dataMultiple requests to follow relationshipsOne request can traverse relationships
Over-fetchingCommon — you get all fields whether you need them or notNever — you only get what you ask for

Core Concepts​

Schema​

The schema defines everything available in the API — every type of data, every query you can run, and every mutation you can perform. Think of it as the API's contract. The Interactive Playground lets you explore the full schema interactively.

Types​

Types describe the shape of data in the API. For example, the Certificate type has fields like name, fingerprint, status, and validity. Types can reference other types — a Certificate has an issuer field that returns a CertificateIssuingDetails type.

type Certificate {
  id: ID!
  name: String!
  fingerprint: String!
  status: CertificateStatus!
  validity: CertificateValidity
  issuer: CertificateIssuingDetails
  # ... many more fields
}

The ! after a type name means the field is non-null — the API guarantees it will always have a value.

Queries​

A query reads data without changing anything — the GraphQL equivalent of a GET request. The Certificate Manager API has 73 queries for retrieving certificates, cloud providers, compliance policies, users, and more.

query {
  certificate(fingerprint: "AB12CD34EF56...") {
    name
    status
    validity {
      notBefore
      notAfter
    }
  }
}

This returns only the name, status, and validity fields — nothing extra.

Mutations​

A mutation changes data — the GraphQL equivalent of POST, PUT, or DELETE requests. Mutations create, update, or delete resources and return the result.

mutation {
  revokeCertificate(
    fingerprint: "AB12CD34EF56..."
    revocationReason: KEY_COMPROMISE
    revocationComment: "Rotating compromised key"
  ) {
    name
    revocation {
      status
      reason
    }
  }
}

The mutation performs the action and returns the updated data in a single round trip.

Fields and Arguments​

Fields are the individual pieces of data you request. In the query above, name, status, and validity are fields on the Certificate type.

Arguments are parameters you pass to narrow down what you want. In certificate(fingerprint: "AB12CD34EF56..."), the fingerprint is an argument that tells the API which certificate to return.

Enums​

Enums are types with a fixed set of allowed values. For example, RevocationReason can be KEY_COMPROMISE, CA_COMPROMISE, AFFILIATION_CHANGED, and others. The reference pages for each enum list all valid values.

Input Types​

For mutations with many parameters, the API groups them into input types rather than listing each argument separately. For example, createCloudProvider takes a single input argument of type CloudProviderInput that contains all the fields needed to create a provider.

How the Reference Documentation is Organized​

The reference pages in this section are auto-generated from the API schema and organized into:

  • Operations — Queries and mutations you can call
    • Each page shows the operation signature, arguments, and return type
    • Arguments and return types link to their type definitions
  • Types — Object types, input types, enums, scalars, unions, and interfaces
    • Each page shows the type's fields with their types and descriptions
    • "Member Of" sections show which other types reference this type

Next Steps​

  1. Authentication — Get your API key and learn how to authenticate
  2. Your First Query — Make real API calls with working examples
  3. Pagination — Understand cursor-based pagination for list queries
  4. Error Handling — Handle errors and partial responses
Try it live

The Interactive Playground lets you build and test queries against your own Certificate Manager environment directly in the browser.