Introducing the AppDirect GraphQL API

Application developers are growing tired of REST. Tired of its rigid data structures. Tired of being sent more data than they need, while simultaneously not being sent enough. Tired of juggling multiple API endpoints and multiple API versions. These developers are asking for alternative solutions that enable them to build modern, compelling applications with streamlined workflows on top of platforms. Now, these developers can build these types of experiences on top of the AppDirect platform as well.

Throughout 2020, AppDirect product teams have been hard at work addressing this need and today we are excited to announce Preview Availability of the AppDirect GraphQL API.

What is GraphQL?

GraphQL is an open-source query language for APIs that serves as a modern alternative to traditional REST API architectures. GraphQL has been widely adopted by, and offered through, other market leading platforms like Github, Shopify, Netflix, and Paypal since the original specification was publicly released by Facebook in 2015.

Using GraphQL, an application builds a request for the data it needs, then sends this request to a single endpoint on the API server. For example, a typical GraphQL query to retrieve user data might look like the following:

POST https://api.example.com/graphql

query {
  users {
      id
      firstName
      lastName
  }
}

Response:

{
    "data": {
        "users": [
            {
                "id": 1,
                "firstName": “William”,
                "lastName": “Smith”
            },
            {
                "id": 2,
                "firstName": “Helen”,
                "lastName": “Larson”
            }
        ]
    }
}

A similar pattern is used to mutate (create, update, and delete) data as well. 

What are the benefits of GraphQL?

Much has been written about the benefits of GraphQL over REST. A quick Google search will yield a number of excellent articles on this topic. For this post I would like to focus on two key benefits that will resonate with developers familiar with the AppDirect REST API: 

Type safety and hierarchical structure

All GraphQL APIs are described by a schema that uses a strong type system to define the data objects available within the API and how they can be accessed. The schema becomes a valuable contract (with built-in documentation) that can be used by application developers to quickly build their solutions.

In addition to the type system, GraphQL schemas naturally lend themselves to organizing API data into a graph of interconnected objects. Users link to companies, companies link to subscriptions, and subscriptions link to orders and products. The hierarchical and connected nature of GraphQL schema is an effective and intuitive way for application developers to quickly understand the systems they are building on.

Resolves over-fetching and under-fetching issues

One key challenge of building applications with RESTful APIs is how to efficiently retrieve the data that an application needs. The rigid nature of REST API data structures and endpoints will often result in more data being sent to an application than is actually needed. For example, to get a user’s email address an application may call an API that returns all user attributes even though only email is needed. This is an example of over-fetching and may impact user experience and overall performance of an application, especially for large datasets or for users with slow network connections.

The same is true for under-fetching data, although in the opposite way. When an API call does not return all data required by an application, the application must make multiple API calls to retrieve the additional data. Similar to over-fetching, this degrades performance and user experience.

GraphQL solves both problems by allowing applications to query for the exact data they need and to do so with a single call. For example, imagine an application that needs to retrieve all users in a system and for each user to get the groups they belong to. In a typical REST architecture, retrieving this data would require multiple API calls for every user in the system. Using GraphQL, the query can be done with a single call that only returns the data the application needs:

Query:

POST https://api.example.com/graphql

query {
  users {
      id
      firstName
      lastName
      groups {
           name 
      } 
  }
}

Response:

{
    "data": {
        "users": [
            {
                "id": 1,
                "firstName": “William”,
                "lastName": “Smith”,
                “groups” : [
                    {name: “Marketing”},
                    {name: “Sales”} 
                ]
            },
            {
                "id": 2,
                "firstName": “Helen”,
                "lastName": “Larson”
                “groups” : [
                    {name: “Engineering”} 
                ]
            }
        ]
    }
}

What is supported with the Preview today?

For our initial GraphQL release we wanted to find an area of the AppDirect platform that developers would immediately benefit from, yet an area sufficiently complex enough so as to showcase the power and benefits that a GraphQL API offers. We quickly realized that an API to manage the product catalog would be a perfect fit.

Products in the AppDirect platform are complex objects made up of a number of parts (profile and branding data, editions and pricing, integration configuration) that would be a natural fit within a GraphQL API.

With today’s preview availability, it will be possible to create, update, and publish products to a marketplace catalog. This will be especially powerful for developers tasked with automating routine product changes to marketing pages, fee structures, editions, or running regular health checks on the product itself.

Look out for future blog posts that will go into more detail on the Product Management API.

What comes next?

Today’s GraphQL introduction marks a major milestone in AppDirect’s API product offering, but it’s just the beginning. As we enter 2021, AppDirect will continue to iterate on the Product Management API, increasing its production readiness so that it can be brought out of preview availability. At the same time, we will expand the GraphQL API beyond Product Management and into other parts of the AppDirect platform, such as billing, subscription, and identity management. Eventually the entire AppDirect platform will be addressable through our GraphQL API. We hope that you are as excited about this as we are.

If you are interested in learning more about the API itself, see our API Documentation. If you are interested in being part of the preview phase, contact your Account Executive or Customer Success Manager.

Edward Sutter is Director of Product Management at AppDirect