Skip to main content

​
Overview

This endpoint demonstrates KrakenD’s ability to convert GraphQL APIs into REST endpoints, allowing REST clients to consume GraphQL data without knowing the GraphQL query language. HTTP Method: GET
Endpoint: /starwars_films/{movie_id}

​
Parameters

​
movie_id
string
required
The Star Wars film ID (1-6). Valid values:
  • 1 - The Phantom Menace
  • 2 - Attack of the Clones
  • 3 - Revenge of the Sith
  • 4 - A New Hope
  • 5 - The Empire Strikes Back
  • 6 - Return of the Jedi

​
What It Demonstrates

  • GraphQL to REST Conversion: Exposes a GraphQL API as a RESTful endpoint
  • GraphQL Query Execution: Executes complex GraphQL queries behind the scenes
  • Variable Interpolation: Maps URL path parameters to GraphQL variables
  • Target Extraction: Extracts specific fields from nested GraphQL responses

​
Request Example

curl http://localhost:8080/starwars_films/4

curl http://localhost:8080/starwars_films/1

​
Expected Response

{
  "id": "ZmlsbXM6NA==",
  "episodeID": 4,
  "title": "A New Hope",
  "director": "George Lucas",
  "releaseDate": "1977-05-25",
  "speciesConnection": {
    "species": [
      {
        "name": "Human",
        "classification": "mammal",
        "homeworld": {
          "name": "Tatooine"
        }
      },
      {
        "name": "Droid",
        "classification": "artificial",
        "homeworld": null
      },
      {
        "name": "Wookiee",
        "classification": "mammal",
        "homeworld": {
          "name": "Kashyyyk"
        }
      }
    ]
  }
}

​
Backend Service

  • Host: https://swapi-graphql.netlify.app/
  • URL Pattern: /.netlify/functions/index
  • Type: GraphQL API
  • Target: data.film (extracts the film object from the GraphQL response)

​
GraphQL Query

KrakenD executes this GraphQL query behind the scenes: 
query Query ($movie_id: ID!) {
  film (filmID: $movie_id) {
    id
    episodeID
    title
    director
    releaseDate
    speciesConnection {
      species {
        name
        classification
        homeworld {
          name
        }
      }
    }
  }
}
Variables: 
{
  "movie_id": "4"
}

​
KrakenD Configuration

{
  "@comment": "Feature: GraphQL to REST",
  "endpoint": "/starwars_films/{movie_id}",
  "backend": [
    {
      "host": ["https://swapi-graphql.netlify.app/"],
      "url_pattern": "/.netlify/functions/index",
      "target": "data.film",
      "extra_config": {
        "backend/graphql": {
          "type": "query",
          "query": "query Query ($movie_id: ID!) {\nfilm (filmID: $movie_id) {\nid\nepisodeID\ntitle\ndirector\nreleaseDate\nspeciesConnection {\nspecies {\nname\nclassification\nhomeworld {\nname\n}\n}\n}\n}\n}",
          "variables": {
            "movie_id": "{movie_id}"
          }
        }
      }
    }
  ]
}

​
Key Configuration Options

​
backend/graphql

Configures the GraphQL integration: 
{
  "backend/graphql": {
    "type": "query",
    "query": "...",
    "variables": {
      "movie_id": "{movie_id}"
    }
  }
}
  • type: "query" - Specifies this is a GraphQL query (not a mutation)
  • query: The GraphQL query string with placeholders
  • variables: Maps URL path parameters to GraphQL variables

​
target

Extracts a specific field from the GraphQL response: 
"target": "data.film"
GraphQL APIs typically return: 
{
  "data": {
    "film": { ... }
  }
}
The target configuration extracts just the film object, making the response cleaner for REST clients.

​
Variable Interpolation

"variables": {
  "movie_id": "{movie_id}"
}
KrakenD automatically replaces {movie_id} with the value from the URL path.

​
Use Cases

  • Legacy Integration: Expose modern GraphQL APIs to legacy REST clients
  • Simplified Client Code: Clients don’t need GraphQL libraries or knowledge
  • API Gateway Pattern: Provide a unified REST interface to mixed backend types
  • Mobile Apps: Reduce client complexity by handling GraphQL on the gateway
  • Third-party Integrations: Make GraphQL APIs accessible to partners expecting REST

​
GraphQL Mutations

While this endpoint demonstrates queries, KrakenD also supports GraphQL mutations: 
{
  "backend/graphql": {
    "type": "mutation",
    "query": "mutation CreateUser($name: String!) { ... }",
    "variables": {
      "name": "{name}"
    }
  }
}

​
Error Handling

If an invalid movie_id is provided: Request: 
curl http://localhost:8080/starwars_films/999
Response: 
{
  "error": "film not found"
}
KrakenD properly handles GraphQL errors and returns appropriate HTTP status codes.

Build docs developers (and LLMs) love

Get started for freeTalk to us