Skip to main content

Why GraphQL?

· 5 min read
Ben Eliott
Ben Eliott
Developer

If you're building integrations today, you already know REST. It's reliable, familiar, and here to stay. GraphQL doesn’t replace it outright, but it does give you a different way to think about retrieving and shaping data. In the context of a Legalesign integration, we treat GraphQL as a first-class API, so every part of the platform is available through it. If your project starts asking for custom views, or more complex functionality, GraphQL is where you can find that capability.

This post walks through where GraphQL came from, how it compares to REST, how to use it, and its use at Legalesign.

TL;DR

  • REST exposes multiple endpoints (think /users, /documents) that each return a predefined payload. It’s predictable but can mean several calls or extra data you never use.
  • GraphQL exposes a single endpoint where you describe the exact data shape you want. The server responds with only those fields, even across related objects.
  • Legalesign exposes the entire platform through GraphQL, so anything you see in the UI is available via the API.

Where is it from and what is it exactly?​

Facebook created GraphQL to power its mobile apps, then open-sourced it in 2015. The idea is straightforward: you describe the data you want, and the server replies with JSON that matches the exact shape of your request. One query can include fields from multiple related objects, so you skip the choreography of calling /users, then /documents, then /signers.

Because GraphQL APIs are strongly typed and introspectable, the schema doubles as live documentation. You can see what’s available, learn how objects relate, and try queries in one place.

Legalesign ships an interactive GraphiQL interface for this purpose. Log in with your Legalesign credentials, inspect the schema, and run queries or mutations directly in the browser when you want to prove out an idea.

REST vs GraphQL​

While REST and GraphQL both aim to expose data over HTTP, their philosophies differ.

FeatureRESTGraphQL
EndpointsMultiple (/users, /contracts, etc.)Single (/graphql)
Data FetchingFixed per endpointFlexible, client-defined queries
Over-fetching / Under-fetchingCommonReduced
VersioningOften versioned (/v1/, /v2/)Versionless
AuthenticationAPI key (at Legalesign)OAuth

In REST you must adapt to what each endpoint provides.

In GraphQL, you define the contract. That means asking for just the fields you need—even across related entities—in a single operation.

Want more detail? These companion posts dive deeper:

Authentication at Legalesign​

At Legalesign, REST uses dedicated API keys. GraphQL uses OAuth 2.0 instead, which brings token-based security, delegated permissions, and fine-grained scopes. If you already have a Legalesign account, you’re ready to authorize and start querying.

Once authenticated via OAuth, developers can query and mutate any available data securely, benefiting from both OAuth’s robust access model and GraphQL’s efficiency.

Legalesign Is API-First with GraphQL​

Every feature available in the Legalesign platform — from contracts and templates to workflows, signers, and audit trails — is accessible through the GraphQL API.

Here's an example of a query that pulls the first 1000 unarchived sent documents from 'myGroup', along with the total count, name, status and timestamp:

query listSentDocs {
  group(id: "myGroup") {
    documentConnection(
      archived: false
      after: 0
      first: 1000
    ) {
      documents {
        name
        status
        created
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
}

The schema exposes the full platform, so you can fetch related entities in one round trip, shape responses for your UI, and discover new capabilities through introspection in GraphiQL.

Why Use GraphQL Over REST​

REST remains a great default, but GraphQL shines when you want:

  • Precision and efficiency: Ask for what you need, nothing more. That cuts payload size and latency.
  • One entry point: All queries and mutations go through /graphql, so you don’t juggle versions or endpoint discovery.
  • Flexible retrieval: Complex UI views often need data from multiple entities; GraphQL lets you compose that in a single query.
  • Strong typing: The schema defines every field and argument, which keeps responses predictable and enables client-side validation.
  • Discoverability: Introspection plus tools like GraphiQL make it easy to explore and prototype.
  • Versionless evolution: Adding new fields doesn’t break existing queries, so you iterate without version bumps.

Taken together, developers ship faster and spend less time reconciling payloads.

Summary​

Use REST when it’s the fastest route to value. Reach for GraphQL when you want to combine data, trim payloads, or experiment quickly. You also get strong typing, self-documentation, and full access to the platform from a single endpoint—no matter what your next integration requires.

Get Started & Read More​

Explore the Legalesign GraphQL API documentation and try your queries in the GraphiQL interface.

To dive deeper into related topics, see: