Why Hygraph's API is the best one out there

In my journey through using and implementing various content management systems over the years, Hygraph stands out from the crowd, every single time.

Hygraph offers a unique blend of power, flexibility, and ease of use that I haven’t found in other solutions. Its GraphQL Content API is not just another headless CMS offering – it’s a game changer that has redefined my approach to content management and delivery.

In this post, I’ll share my firsthand experience with Hygraph, diving into the features that make it my top choice for every project. From its intuitive API design that feels natural even to GraphQL newcomers, to advanced capabilities like localization and asset transformation, I’ll show you why Hygraph has consistently outperformed other options in the market.

Let’s begin.

#Simplicity and intuitive API design

One of the standout features of Hygraph’s GraphQL Content API is its remarkable API design. Hygraph has managed to create an API that feels familiar and approachable, even for those new to GraphQL.

While GraphQL itself can be intimidating for newcomers, Hygraph’s implementation feels natural and easy to grasp. The APIs structure mirrors the content fields and relationships defined by you, making it intuitive to query and manipulate data.

Here’s what it looks like to query content to fetch a blog post:

query GetProduct($sku: String!) {  
  product(where: { sku: $sku }) {  
    name  
    manufacturer {  
      name  
    }  
    description {  
      text  
    }  
  }  
}

Even if you’re new to GraphQL, this query is readable and self-explanatory. You’re asking for a product with a specific slug, and you want its name, the manufacturer's name, and the description text.

The true power of a CMS comes when authors can deal with multiple versions, including draft and published articles. Hygraph allows developers to create multiple content stages, and entries can be published to a specific stage, with the ability to compare and rollback if necessary.

Here’s how easy it is to query from the DRAFT content stage, often useful for staging environments for editors to review and approve/reject entries.

query getProduct($sku: String!) {  
  product(where: { sku: $sku }, stage: DRAFT) {  
   name  
    manufacturer {  
      name  
    }  
    description {  
      text  
    }  
  }  
}

#Great developer experience

You’ll read in this article many other great features of Hygraph, but the one that stands out the most is its attention to the developer experience (DX).

Documentation

A GraphQL superpower is that is it’s “self documenting”, but Hygraph doesn’t just stop there. It provides documentation for developers, and editors that include:

• Clear explanations of concepts and features
• Step-by-step tutorials and guides for common tasks (as well as integrations with third party services)
• Detailed API Reference documentation for all things GraphQL (in addition to the “self documenting” GraphQL Playground)
• And much more!

Playground environment

If you’ve worked with another GraphQL API before, then you’ll be familiar with GraphiQL. Hygraph integrates this inside its “Studio” interface so developers can get started using the API using an interface that is familiar to them.

GraphiQL allows you to:

• Explore the API schema is real time (see schema changes updated instantly)
• Execute GraphQL queries (and mutations) in the browser
• Test against content stages and localization features

Predictable naming conventions

Naming things is hard. There are many ways to create and expose entities as GraphQL, but Hygraph takes a simple approach with its naming. This includes:

• Clear and descriptive names for types, fields and operations – you can also override naming where needed
• Enforces validation for camelCase names for any fields you override, as well as using a strict PascalCase for type names that is common amongst good GraphQL schema design
• Intuitive pluralization for collection queries, e.g. article vs articles

Webhooks

Hygraph doesn’t get in your way when you need to process additional logic when something occurs inside the CMS. You can use webhooks to trigger your own code when something is published, unpublished, moved from one content stage to another, deleted, and much more.

Extensibility

I wouldn’t expect a CMS to solve every possible use case or problem. This is why Hygraph has an escape hatch for developers and editors who need more from the Hygraph Studio.

Hygraph provides an App Marketplace that is growing with things you can install to enhance your editors experience. Whether you need to translate some content on the fly, or integrate your own Digital Asset Management platform, Hygraph has you covered.

#Advanced asset transformations

Content management isn’t just about text – it’s also about images, videos, and other media assets. Hygraph shines in this area with its advanced asset transformation features, all accessible through the GraphQL API.

Creating thumbnails, which is a common requirement, is remarkably straightforward with Hygraph. You don’t need to worry about processing or transforming images yourself, instead you can generate the exact thumbnail you need at query time:

query {  
  asset(where: { id: "..." }) {  
    url  
    thumbnailUrl: url(  
      transformation: {  
        image: {  
          resize: { width: 100, height: 100, fit: clip }  
        }  
      }  
    )  
  }  
}

In this query, we’re fetching both the original url of the asset, and a transformed thumbnail url, prefixed using GraphQL Aliases. This approach simplifies your codebase and leverages the power of Hygraph.

#It’s not just GraphQL

The Hygraph GraphQL API embraces the full power of GraphQL, including support for Fragments, and Directives. Fragments are commonly used to avoid repeating yourself in cases like this:

fragment ArticleFields on Article {  
  title  
  excerpt  
  publishDate  
}

query {  
  recentArticles: articles(orderBy: publishDate_DESC, first: 5) {  
    ...ArticleFields  
  }  
  featuredArticle: article(where: { isFeatured: true }) {  
    ...ArticleFields  
    content {  
      text  
    }  
  }  
}

But the true power of GraphQL Fragments comes when you use the Relay Specification, which Hygraph supports out of the box whereby you specify data dependencies for components using GraphQL Fragments.

#Superior localization features

It’s important for websites that serve a global audience to also serve content in a language that is specific to that country or region. Hygraph’s GraphQL Content API makes localization a first class property when authoring content, and querying content.

One of the many super powers of GraphQL is its ability to accept arguments for the fields you request:

query {  
  en: article(where: { slug: "welcome-to-hygraph" }, locale: en) {  
    title  
  }  
  fr: article(where: { slug: "welcome-to-hygraph" }, locale: fr_FR) {  
    title  
  }  
}

This is incredibly useful when requesting content in multiple locales:

Hygraph is smart enough to know that if you forget to add the translated content for a field, it will fallback to the system default you have configured.

#Extended GraphQL type system

Those familiar with GraphQL will know of its limited scalar types – String, Int, Float, Boolean, and ID.

Hygraph extends the default GraphQL scalar types and provides its own – Rich Text, Markdown, Location, JSON, and many more.

Developers interacting with Rich Text returned from the API would be pretty disappointed if the output was only available as HTML. It would require a lot of parsing and transforming of HTML entities to change the appearance of content.

Instead, Hygraph provides a Rich Text type that gives developers the Rich Text as an Abstract Syntax Tree (AST) so how Rich Text is presented is up to the developer.

Hygraph takes it even further by allowing users to embed content entries that it already knows about stored in the CMS. This means that if users are describing a product, or a product add-on, the exact product details (images, price, etc.) can be represented alongside the text.

Rendering the AST with your own customizations is made really easy by using the open source Rich Text Rendering libraries.

Simplified polymorphic relations

In traditional database design, managing relationships between multiple types of entities often requires complex “through” or “pivot” tables for true normalized schemas.

Hygraph leverages GraphQL’s union types to implement polymorphism. This approach allows you to create fields that can contain multiple types of content, providing incredible flexibility in your content modeling.

For example, let’s imagine you build a website that features different types of content blocks – text, images, and videos. With Hygraph, you can easily model this:

type Page {  
  title: String!  
  content: [ContentBlock!]!  
}

union ContentBlock = TextBlock | ImageBlock | VideoBlock

type TextBlock {  
  text: String!  
}

type ImageBlock {  
  image: Asset!  
  caption: String  
}

type VideoBlock {  
  video: Asset!  
  duration: Int!  
}

In this model, a Page can have multiple ContentBlock items, each of which could be a TextBlock, ImageBlock, or VideoBlock. Fetching this from the CMS via GraphQL is just as easy:

query {  
  page(where: { id: "page123" }) {  
    title  
    content {  
      __typename  
      ... on TextBlock {  
        text  
      }  
      ... on ImageBlock {  
        image {  
          url  
        }  
        caption  
      }  
      ... on VideoBlock {  
        video {  
          url  
        }  
        duration  
      }  
    }  
  }  
}

The __typename response that is returned inside each content block is perfect for matching the required frontend component.

It’s also worth noting that relations can be configured in unidirectional and bidirectional references. Unidirectional is perfect for one-way references where only one side is aware of the other, whereas bidirectional allows both entities to know each other.

#Content mutations

While many CMS APIs focus solely on content delivery, Hygraph takes it a step further by providing full capabilities to Create, Read, Update, and Delete content entries through its high performance GraphQL API.

mutation {  
  createArticle(data: {  
    title: "New Article",  
    content: { text: "This is the content of the new article." }  
  }) {  
    id  
    title  
  }  
}

From user-generated content to automated content updates by third party events. This feature alone increases the amount of use cases that a single CMS can cover.

#Programmatic schema management

While Hygraph boasts a pretty nice “no code” UI for managing schema, it does give developers the tools to use code to control everything below the Content API.

The Management SDK allows developers to programmatically hook into managing the schema via code.

Here’s how easy it is to use code to create a new model Page:

client.createModel({  
  apiId: 'Page',  
  apiIdPlural: 'Pages',  
  displayName: 'Page',  
});

It’s also just as easy to add fields, configure validation, and add relations:

client.createSimpleField({  
  parentApiId: 'Page',  
  type: SimpleFieldType.String,  
  apiId: 'title',  
  displayName: 'Title',  
  isTitle: true,  
  isRequired: true,  
  visibility: VisibilityTypes.ReadWrite,  
});

client.createRelationalField({  
  parentApiId: 'Page',  
  apiId: 'preview',  
  displayName: 'Preview',  
  type: RelationalFieldType.Asset,  
  isRequired: true,  
  reverseField: {  
    isUnidirectional: true,  
    apiId: 'page',  
    displayName: 'Page',  
    modelApiId: 'Asset',  
  },  
});

#Conclusion

Hygraph’s GraphQL Content API stands out in the crowded field of content management solutions due to its combination of power, flexibility, and ease of use.

From its intuitive design and comprehensive GraphQL feature support to its advanced capabilities like polymorphic relations, localization, and programmatic schema management. Hygraph provides a complete solution for modern content management.

The API’s support for mutations and custom primitive types, including types you connect from third party sources, and its own powerful asset transformation features, makes it suitable for a wide range of applications beyond simple content delivery.

Whether you’re building a multilingual education resource, a complex e-commerce platform, or a dynamic web application, Hygraph’s GraphQL Content API provides the tools you need to manage and deliver your content effectively.

By choosing Hygraph, you’re not just selecting a content API – you’re opting for a forward-thinking approach to content management that can grow and adapt with your needs.