Guidelines for Consuming Entities GraphQL API

Introduction

We provide a GraphQL API built using Hot Chocolate a leading .NET GraphQL server from ChilliCream.

For teams using .NET, we strongly recommend leveraging Strawberry Shake a GraphQL client library also from ChilliCream which provides full client generation based on our GraphQL schema.

This allows for a strongly-typed, resilient, and developer-friendly experience when consuming our API.

---

.NET Client Recommendation: Strawberry Shake

Benefits

• Strong typing for queries, mutations, and responses
• Compile-time error checking
• Built-in support for error handling, state management, and caching
• Automatically generated client code based on our API schema

---

How to Get Started

1. Download GraphQL Schema from our Endpoint

Schema is available at GET https://{...}/entities/entities-api/graphql/v1/schema.graphql. This action will download the entire schema definition which then can be used to generate GraphQl client.

Install and Get Started

All required information is available at Strawberry Shake Get Started page. Simply follow the instructions.

Example Usage

After client has been setup, usage is quite straight forward.

Query Example

public class ProductService
{
    private readonly IYourGraphQLClient _client;

    public ProductService(IYourGraphQLClient client)
    {
        _client = client;
    }

    public async Task<IReadOnlyList<ProductDto>> GetProductsAsync()
    {
        var result = await _client.GetProducts.ExecuteAsync();

        if (result.IsErrorResult())
        {
            // Handle error accordingly
        }

        return result.Data.Products.Select(p => new ProductDto
        {
            Id = p.Id,
            Name = p.Name
        }).ToList();
    }
}

Clients for Other Popular Technologies

Language	Possible Client	Documentation Link
JavaScript / TypeScript	Apollo Client	https://www.apollographql.com/docs/react/
Python gql	(GraphQL client for Python)	https://gql.readthedocs.io/en/latest/
PHP	GraphQL Client (softonic/graphql-client)	https://github.com/softonic/graphql-client
Go	machinebox/graphql	https://github.com/machinebox/graphql
Java	Apollo Android / Netflix DGS Framework	https://netflix.github.io/dgs/

General Best Practices

• Always use generated clients when possible (strong typing, less error-prone).
• Avoid manually building GraphQL queries in raw strings unless absolutely necessary.
• Treat the schema as the single source of truth — regenerate your client when the schema changes.
• Handle errors gracefully — GraphQL errors come back in a standard format.
• Be mindful of API versioning and breaking changes — follow provided changelogs.

Additional Resources

• Hot Chocolate Docs: https://chillicream.com/docs/hotchocolate
• Strawberry Shake Docs: https://chillicream.com/docs/strawberryshake
• GraphQL Best Practices: https://graphql.org/learn/best-practices/