Exposing GraphQL as REST APIs

In order to handle complicated business problems, modern systems frequently need to work with hundreds or even thousands of APIs. Because of its powerful API composition capabilities, GraphQL has been adopted by numerous organisations. But switching to GraphQL can be difficult. It involves a lot of team training as well as major adjustments to frontend and backend architectures.

That's why Tailcall has developed a directive called @rest to streamline this transition and take advantage of GraphQL's power without requiring a complete overhaul. With the help of this directive, Tailcall GraphQL queries and mutations may be made available as REST endpoints.

How it works

This guide show you how to expose REST endpoints for your GraphQL operations by using the @rest directive like follows:

There are three main steps to this process:

Define your Tailcall GraphQL configuration file.
Define an operation using @rest directive in a separate file.
Link the operation to the main config file.

Example

Step 1: Define your GraphQL configuration

schema
  @upstream(
    baseURL: "https://jsonplaceholder.typicode.com"
  ) {
  query: Query
}

type Query {
  post(id: Int!): Post @http(path: "/posts/{{.args.id}}")
}

type Post {
  userId: Int!
  id: Int
  title: String
  body: String
  user: User @http(path: "/users/{{.value.userId}}")
}

type User {
  id: Int!
  name: String!
  username: String!
  email: String!
  phone: String
  website: String
}

for more information on how to define your Tailcall GraphQL configuration file, please refer to the Tailcall GraphQL Configuration.

Step 2: Define an operation using `@rest` directive

We will define an operation and use the @rest directive to define a REST endpoint for the operation. We will create a new file and add the following content to it. Save the file with the filename: user-operation.graphql. You can name the file anything you want, but make sure to link it to the main config file in the next step.

query ($id: Int!) @rest(method: GET, path: "/post/$id") {
  post(id: $id) {
    id
    title
    body
    user {
      id
      name
    }
  }
}

to know more about the @rest directive, please refer to the Tailcall GraphQL Directives.

Step 3: Link the operation to the main config file

checkout the @link directive in the config snippet below to link the operation file. This step is crucial to make the REST endpoint available.

schema
  @upstream(baseURL: "https://jsonplaceholder.typicode.com")
  @link(type: Operation, src: "user-operation.graphql") {
  query: Query
}

To know more about the @link directive, please refer to the Tailcall GraphQL Directives.

Response

REST Demo

In summary, by utilizing the @rest directive, we've seamlessly exposed RESTful services over Tailcall's GraphQL, enhancing the traditional posts API to offer richer functionality without additional code. This approach combines the simplicity and ubiquity of REST with the modularity and flexibility of GraphQL, allowing for easy consumption from any HTTP client while leveraging GraphQL's powerful data querying capabilities.

How it works​

Example​

Step 1: Define your GraphQL configuration​

Step 2: Define an operation using @rest directive​

Step 3: Link the operation to the main config file​

Response​