Get Started with GraphQL

Introduction

This guide is designed for developers who want to integrate Legalesign's e-signature services using either the REST API or the GraphQL API. It provides an overview of both APIs, with a focus on getting started with GraphQL.

Comparing REST and GraphQL APIs

API developers building e-signature solutions can choose between two APIs to access Legalesign services: REST, which is a traditional and well known format, or GraphQL, which is a newer, more flexible and more comprehensive format.

GraphQL is a query language for APIs that:

• Allows you to request only the data you need.
• Uses a single endpoint instead of multiple endpoints like REST.
• Lets you define the structure of the response.

Often your choice of these two will depend on your development environment but, generally speaking, either API can be used with any coding language. In this guide we assume that you are familiar with JSON, a coding language and basic internet requests.

Why GraphQL can do more than the REST API.

Legalesign is API-first with GraphQL. Anything you can do in the web app, you can do in GraphQL. It's much more powerful to access all the capability within Legalesign. For a quick start we recommend the REST API. But there's no reason you can't use both.

Using the TypeScipt/JavaScript SDK

If you are a TypeScript/JavaScript developer then you may wish to review the TS/JS SDK which uses the GraphQL API and covers some use-cases. But familiarity with the GraphQL itself will provide you with the full scope of function from Legalesign. Read more about SDK vs GraphQL.

Getting Started with GraphQL

The best way to begin is by using the Legalesign GraphQL Explorer (you'll need to have an active account to use it).

The GraphQL Explorer is an interactive tool that lets you:

• Write and test queries and mutations.
• View the full GraphQL schema to understand available fields and operations.
• Debug and refine your queries before integrating them into your code.

info

As long as you are logged into the main app, you can immediately run queries or mutations — authentication (OAuth) is already handled.

Copy and paste this simple query:

query myInfo {
    user {
        id        
        firstName
        lastName
        email
    }
}

The screenshot below shows GraphQL Explorer. Use the top-left icon to view the full GraphQL schema. Paste your GraphQL code into the right-hand window and press the 'play' button.

Figure 1: The GraphQL Explorer interface.

info

We recommend making queries in the GraphQL explorer to get started. This will confirm that your account and credentials are in good order, and help you become familiar with GraphQL syntax before integrating it into your coding projects. You can always use this tool to check and test the behaviour of your queries before you put it into your code.

The result to the query above should look like the following JSON:

{
  "data": {
    "user": {
      "id": "dXNyNjBkNWNkODktMDg3NS00ZXC67mItZjI3ODA5NjgwMDdl",
      "firstName": "Tester",
      "lastName": "Api",
      "email": "api.tester@legalesign.com"
    }
  }
}

This query lets an authenticated user retrieve their own id, firstName, lastName, and email.

GraphQL also supports more complex, tree-like queries, as well as mutations, which let you modify data and trigger actions on the platform.

tip

The entire web app runs on GraphQL. You can inspect network requests in the browser console to find ready-made queries—simply copy and reuse them.

Conclusion

The GraphQL API offers unparalleled flexibility and control for integrating Legalesign services. Start by exploring the GraphQL schema and testing queries in the GraphQL Explorer. Once you are comfortable, integrate these queries into your code to build powerful e-signature solutions.