Another THING. Why GraphQL?
If you're a developer, you know REST. For many years, REST has been the dominant approach. You'll also know that GraphQL hasn't taken over, REST is as strong as ever.
So no, you don't have to use GraphQL and Legalesign won't drop REST any time soon. But if you gravitate to REST only because you already know it, take a moment to consider GraphQL. It's here and may help you as you dive deeper into your integration.
This article simply aims to give you a full understanding of the differences and implications. You're not locked in at any time and you can use either interface as you see fit.
TL;DR:
REST exposes multiple endpoints — such as /users or /documents — each returning predefined data. This structure works well but it's inefficient - you fetch more data than needed or need several calls to assemble a complete view.
GraphQL is a single endpoint to query exactly the data you require, combining flexibility, precision, and performance.
Also - it does everything.
Where is it from and what is it exactly?
GraphQL was originally developed by Facebook and released as open source in 2015.
It enables you to shape a request for precisely what data you need, and the server responds with a JSON object shaped to that request.
Rather than hitting multiple REST endpoints, you make a single query that can include multiple fields and relationships.
The GraphQL engine resolves these queries across different data sources and returns a unified, predictable result.
PLUS, GraphQL APIs are strongly typed (you definitely want that) and the whole thing is self-documenting. You can use the self-documenting feature to explore and test any combination of data very easily which is, basically, awesome.
The GraphQL Schema is a structured text document that defines all available types, fields, and operations, which can be introspected directly.
You can explore these capabilities using Legalesign’s GraphiQL interface, which provides an interactive environment for running queries and inspecting the schema. Just login with your Legalesign credentials and start using it. This is a key tool you'll use a lot.
REST vs GraphQL
While REST and GraphQL both aim to expose data over HTTP, their philosophies differ.
| Feature | REST | GraphQL |
|---|---|---|
| Endpoints | Multiple (/users, /contracts, etc.) | Single (/graphql) |
| Data Fetching | Fixed per endpoint | Flexible, client-defined queries |
| Over-fetching / Under-fetching | Common | Eliminated |
| Versioning | Often versioned (/v1/, /v2/) | Versionless |
| Authentication | API key (at Legalesign) | OAuth |
In REST you must adapt to what each endpoint provides.
In GraphQL, you define the data contract, requesting only what you need — even across related entities — in one operation.
To see how GraphQL solves “overfetching,” read What’s Overfetching?.
If you're interested in handling large result sets or pagination, see I Want It All (Paginated Requests).
For a deeper look into query structure, check out Designing Queries in GraphQL and Connections in GraphQL.
Authentication at Legalesign
At Legalesign, the REST interface is a dedicated API key. However the GraphQL uses OAuth 2.0 for authentication. OAuth provides token-based security, delegated permissions, and fine-grained control. With OAuth if you have a Legalesign account you're already ready to go.
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.
The GraphQL library exposes the full platform schema, providing complete access to all functionality in one consistent interface. Developers can retrieve related entities in a single request, shape responses to match their use case, and explore available queries and mutations dynamically through schema introspection — directly via the Legalesign GraphiQL interface.
In effect, GraphQL gives you complete programmatic access to everything Legalesign can do, through a single endpoint. Good huh?
Why Use GraphQL Over REST
While REST remains a widely adopted standard, GraphQL offers several clear advantages when building modern integrations:
- Precision and Efficiency: Clients can specify exactly which fields and relationships to return. This eliminates over-fetching (too much data) and under-fetching (too little data), improving both speed and efficiency.
- Single Endpoint: All queries and mutations are handled through one endpoint, simplifying API structure and reducing maintenance overhead.
- Flexible Data Retrieval: A single GraphQL query can replace multiple REST calls, making it easier to assemble complex data or UI views.
- Strong Typing and Validation: GraphQL schemas define every object and field, ensuring predictable responses and enabling automated client generation and validation.
- Discoverability: Built-in introspection allows developers to explore available data, types, and operations directly within the API — for example, using GraphiQL.
- Versionless Evolution: GraphQL APIs evolve by adding new fields and types, without breaking existing queries or requiring versioned endpoints.
For developers, this translates to faster development cycles, reduced API complexity, and more maintainable integrations.
Summary
REST API will work, and if you already know it, it gets you off to a quick start.
Requests to GraphQL can give you precisely the data you need, in one call.
GraphQL is strongly typed and that's reassuring for any development project.
The self-documenting GraphiQL interface gives you both full introspection powers and a playground to test your queries and mutations.
At Legalesign, adopting GraphQL as part of our API-first architecture means developers can access every feature through a single, consistent, and secure interface - providing a reassuringly deep resource too, for whatever your product manager dreams up next.
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: