REST and GraphQL are two terms Directus throws around a lot – and there’s a good reason for that. As a completely open-source and unopinionated platform, we strive to accommodate many various datastores and flexible ways to interact with the data within. Depending on your business or project requirements, you will lean toward using either REST or GraphQL, so we designed our API to be able to accommodate both options.
While REST – an architectural specification that describes an interface between decoupled endpoints (or resources) – has been used widely since its introduction in 2000, GraphQL is relatively new. Invented by Facebook in 2012, it provides an open-source data query and manipulation language for APIs along with a runtime for fulfilling data queries.
Using a GraphQL API, you can leverage a nested list of all the data you need to pull from your database. That list is sent to a single API endpoint, and it returns all the various pieces of data you need – with just one request. It’s a very clean, efficient way to complete requests. By contrast, a REST API typically requires you to make individual queries for each type of data you need to retrieve. While equally accurate, it can be slower and less efficient, because it requires some manual labor to string together all of the various data points. This could be unfortunate for developers whose requirements calls for the REST specification.
Directus provides behavior parity between its REST and GraphQL APIs, eliminating the need to send multiple requests to get all of the data you need. It enables you to leverage the REST API in the same way as the GraphQL API, and retrieve multiple data points with a single query.
How Does It Work?
The Directus API uses Database Mirroring to dynamically generate both REST endpoints and a GraphQL schema, based on the connected database’s schema. They are interaction points, with everything underneath being shared as an abstract syntax tree (AST) – the tables, the columns and everything that defines the architecture of your database. As a result, both APIs are structured in the exact same way – dynamically.
The API has predictable resource-oriented URLs, relies on standard HTTP status codes, and uses JSON for input and output. Since it’s generated based on your specific schema and configurations, the API output will differ between installations, however, there’s absolutely no difference in the functionality between the REST endpoints and the GraphQL schema – they are mapped to the same core set of core services, so you don't lose any performance or capabilities by choosing one over the other.
To query data using the REST API:
To query data using the GraphOL API:
With Directus, you’re not beholden to any one way of doing things. You can start out using the more common REST format that you’re familiar with, then switch over to GraphQL later on, if desired.
Always Flexible, Forever Open and Unopinionated
Our goal here at Directus is to deliver software that’s flexible enough to inherit your chosen technology stack, based on your project and business requirements, personal preference and skill set, so you can be free to innovate and create amazing data-driven experiences with our platform. Over the coming months, we’ll be working on a new tool called WebSockets, which will enable real-time data retrieval for continuous updates. This tool will be available in both the REST API and as GraphQL Subscriptions – you simply subscribe to data and when it changes, your application updates automatically.
Directus REST and GraphQL behavior parity overlaps with other great tools to provide a robust, completely unopinionated experience. Learn about other key tools by reading more of our Spotlights, or try Directus today.