Calling the API

Fresh

This page covers how to call the IMDb GraphQL API from multiple environments: AWS CLI, Postman, TypeScript (proxy and one-off), Java, and Python.

AWS CLI

The AWS CLI provides a quick way to test API calls without writing code. Use the dataexchange send-api-asset command.

Example 1 — Simple Rating Query (Titanic)

bash

aws dataexchange send-api-asset \
  --data-set-id "YOUR_DATA_SET_ID" \
  --revision-id "YOUR_REVISION_ID" \
  --asset-id "YOUR_ASSET_ID" \
  --request-headers '{"x-api-key":"YOUR_API_KEY"}' \
  --method "POST" \
  --path "/" \
  --body '{"query":"{ title(id: \"tt0120338\") { ratingsSummary { aggregateRating voteCount } } }"}' \
  --region us-east-1

Example 2 — Complex Query (The Matrix — title, ratings, first 10 cast)

bash

aws dataexchange send-api-asset \
  --data-set-id "YOUR_DATA_SET_ID" \
  --revision-id "YOUR_REVISION_ID" \
  --asset-id "YOUR_ASSET_ID" \
  --request-headers '{"x-api-key":"YOUR_API_KEY","Content-Type":"application/graphql"}' \
  --method "POST" \
  --path "/" \
  --body '{
    "query": "{ title(id: \"tt0133093\") { titleText { text } ratingsSummary { aggregateRating voteCount } principalCredits(filter: { categories: [\"cast\"] }) { credits(first: 10) { edges { node { name { nameText { text } } characters { name } } } } } } }"
  }' \
  --region us-east-1

The response is a JSON string containing your query results. Use --output text and --query body flags to extract just the response body if needed.

Postman

Postman is well-suited for exploring the API interactively. Follow these steps to configure a request.

Step 1 — Create a New POST Request

Open Postman and click New > HTTP Request
Set the method to POST

Enter the endpoint URL:

http://api-fulfill.dataexchange.us-east-1.amazonaws.com/v1

Step 2 — Authorization Tab

Click the Authorization tab and configure:

Field	Value
Auth Type	AWS Signature
AccessKey	Your AWS Access Key ID
SecretKey	Your AWS Secret Access Key
AWS Region	`us-east-1`
Service Name	`dataexchange`

Step 3 — Body Tab

Click the Body tab and select the GraphQL mode. Enter your query:

graphql

{
  title(id: "tt0133093") {
    titleText {
      text
    }
    ratingsSummary {
      aggregateRating
      voteCount
    }
    principalCredits(filter: { categories: ["cast"] }) {
      credits(first: 10) {
        edges {
          node {
            name {
              nameText {
                text
              }
            }
            characters {
              name
            }
          }
        }
      }
    }
  }
}

Step 4 — Headers Tab

Add the following headers:

Header Key	Header Value
`Content-Type`	`application/graphql`
`x-amzn-dataexchange-data-set-id`	Your data set ID
`revision-id`	Your revision ID
`asset-id`	Your asset ID
`x-api-key`	Your API key

Expected Response

json

{
  "data": {
    "title": {
      "titleText": {
        "text": "The Matrix"
      },
      "ratingsSummary": {
        "aggregateRating": 8.7,
        "voteCount": 2100000
      },
      "principalCredits": [
        {
          "credits": {
            "edges": [
              {
                "node": {
                  "name": {
                    "nameText": {
                      "text": "Keanu Reeves"
                    }
                  },
                  "characters": [
                    {
                      "name": "Neo"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

GraphQL Playground (TypeScript Proxy)

For ongoing development and exploration, set up a local proxy server that handles AWS signing and exposes a standard GraphQL Playground interface at localhost.

Setup

bash

npm init -y
npm install @aws-sdk/client-dataexchange
npm install --save-dev @types/node ts-node typescript

Create tsconfig.json:

json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Proxy Script (`imdb_playground_proxy_script.ts`)

typescript

import { DataExchangeClient, SendApiAssetCommand } from "@aws-sdk/client-dataexchange";
import * as http from "http";

const client = new DataExchangeClient({ region: "us-east-1" });

const DATA_SET_ID = process.env.IMDB_DATA_SET_ID || "";
const REVISION_ID = process.env.IMDB_REVISION_ID || "";
const ASSET_ID = process.env.IMDB_ASSET_ID || "";
const API_KEY = process.env.IMDB_API_KEY || "";

const PLAYGROUND_HTML = `
<!DOCTYPE html>
<html>
<head>
  <title>IMDb API GraphQL Playground</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/graphql-playground-react/build/static/css/index.css" />
  <script src="https://cdn.jsdelivr.net/npm/graphql-playground-react/build/static/js/middleware.js"></script>
</head>
<body>
  <div id="root"></div>
  <script>
    window.addEventListener('load', function() {
      GraphQLPlayground.init(document.getElementById('root'), {
        endpoint: 'http://localhost:8080/graphql',
        settings: {
          'request.credentials': 'include'
        }
      })
    })
  </script>
</body>
</html>
`;

const server = http.createServer(async (req, res) => {
  res.setHeader("Access-Control-Allow-Origin", "*");
  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type");

  if (req.method === "OPTIONS") {
    res.writeHead(204);
    res.end();
    return;
  }

  if (req.method === "GET" && (req.url === "/" || req.url === "/playground")) {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.end(PLAYGROUND_HTML);
    return;
  }

  if (req.method === "POST" && req.url === "/graphql") {
    let body = "";
    req.on("data", (chunk) => { body += chunk.toString(); });
    req.on("end", async () => {
      try {
        const command = new SendApiAssetCommand({
          DataSetId: DATA_SET_ID,
          RevisionId: REVISION_ID,
          AssetId: ASSET_ID,
          Method: "POST",
          Path: "/",
          RequestHeaders: {
            "Content-Type": "application/graphql",
            "x-api-key": API_KEY,
          },
          Body: body,
        });

        const response = await client.send(command);

        res.writeHead(200, { "Content-Type": "application/json" });
        res.end(response.Body || "{}");
      } catch (error) {
        console.error("API error:", error);
        res.writeHead(500, { "Content-Type": "application/json" });
        res.end(JSON.stringify({ error: String(error) }));
      }
    });
    return;
  }

  res.writeHead(404);
  res.end("Not found");
});

server.listen(8080, () => {
  console.log("GraphQL Playground running at http://localhost:8080/playground");
});

Run

bash

IMDB_DATA_SET_ID=your-id \
IMDB_REVISION_ID=your-id \
IMDB_ASSET_ID=your-id \
IMDB_API_KEY=your-key \
npx ts-node imdb_playground_proxy_script.ts

Then open http://localhost:8080/playground in your browser. You can type queries interactively and see results immediately.

Sample Query to Try

graphql

{
  title(id: "tt0068646") {
    titleText { text }
    ratingsSummary { aggregateRating voteCount }
    releaseYear { year }
  }
}

One-off TypeScript Request

For scripted one-off queries without running a proxy server.

Create the Query File (`titanicRatingsQuery.graphql`)

graphql

{
  title(id: "tt0120338") {
    titleText {
      text
    }
    ratingsSummary {
      aggregateRating
      voteCount
    }
    releaseYear {
      year
    }
    runtimeMinutes
  }
}

Create the Request Script (`imdb_api_request.ts`)

typescript

import { DataExchangeClient, SendApiAssetCommand } from "@aws-sdk/client-dataexchange";
import * as fs from "fs";
import * as path from "path";

const client = new DataExchangeClient({ region: "us-east-1" });

async function main() {
  const queryPath = path.join(__dirname, "titanicRatingsQuery.graphql");
  const query = fs.readFileSync(queryPath, "utf-8");

  const command = new SendApiAssetCommand({
    DataSetId: process.env.IMDB_DATA_SET_ID || "",
    RevisionId: process.env.IMDB_REVISION_ID || "",
    AssetId: process.env.IMDB_ASSET_ID || "",
    Method: "POST",
    Path: "/",
    RequestHeaders: {
      "Content-Type": "application/graphql",
      "x-api-key": process.env.IMDB_API_KEY || "",
    },
    Body: JSON.stringify({ query }),
  });

  const response = await client.send(command);
  const result = JSON.parse(response.Body || "{}");

  console.log(JSON.stringify(result, null, 2));
}

main().catch(console.error);

Run

bash

IMDB_DATA_SET_ID=your-id \
IMDB_REVISION_ID=your-id \
IMDB_ASSET_ID=your-id \
IMDB_API_KEY=your-key \
npx ts-node imdb_api_request.ts

One-off Java Request

For Java applications using Maven.

Maven Project Setup

bash

mvn archetype:generate \
  -DgroupId=com.example \
  -DartifactId=imdb-api-client \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

`pom.xml`

xml

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>imdb-api-client</artifactId>
  <version>1.0-SNAPSHOT</version>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>2.16.60</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>auth</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>apache-client</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <archive>
            <manifest>
              <mainClass>com.example.App</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

`App.java`

java

package com.example;

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.auth.signer.Aws4Signer;
import software.amazon.awssdk.auth.signer.params.Aws4SignerParams;
import software.amazon.awssdk.http.*;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.regions.Region;

import java.io.*;
import java.net.URI;
import java.nio.charset.StandardCharsets;

public class App {
    private static final String ENDPOINT = "http://api-fulfill.dataexchange.us-east-1.amazonaws.com/v1";
    private static final String DATA_SET_ID = System.getenv("IMDB_DATA_SET_ID");
    private static final String REVISION_ID = System.getenv("IMDB_REVISION_ID");
    private static final String ASSET_ID = System.getenv("IMDB_ASSET_ID");
    private static final String API_KEY = System.getenv("IMDB_API_KEY");

    public static void main(String[] args) throws Exception {
        String query = "{ title(id: \"tt0120338\") { titleText { text } ratingsSummary { aggregateRating voteCount } } }";
        String body = "{\"query\":\"" + query.replace("\"", "\\\"") + "\"}";

        SdkHttpFullRequest request = SdkHttpFullRequest.builder()
            .method(SdkHttpMethod.POST)
            .uri(URI.create(ENDPOINT))
            .putHeader("Content-Type", "application/graphql")
            .putHeader("x-api-key", API_KEY)
            .putHeader("x-amzn-dataexchange-data-set-id", DATA_SET_ID)
            .putHeader("revision-id", REVISION_ID)
            .putHeader("asset-id", ASSET_ID)
            .contentStreamProvider(() ->
                new ByteArrayInputStream(body.getBytes(StandardCharsets.UTF_8)))
            .build();

        Aws4Signer signer = Aws4Signer.create();
        Aws4SignerParams params = Aws4SignerParams.builder()
            .awsCredentials(DefaultCredentialsProvider.create().resolveCredentials())
            .signingName("dataexchange")
            .signingRegion(Region.US_EAST_1)
            .build();

        SdkHttpFullRequest signedRequest = signer.sign(request, params);

        SdkHttpClient httpClient = ApacheHttpClient.create();
        HttpExecuteRequest executeRequest = HttpExecuteRequest.builder()
            .request(signedRequest)
            .contentStreamProvider(signedRequest.contentStreamProvider().orElse(null))
            .build();

        HttpExecuteResponse response = httpClient.prepareRequest(executeRequest).call();

        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(response.responseBody()
                    .orElseThrow(() -> new RuntimeException("No response body"))))) {
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) sb.append(line);
            System.out.println(sb.toString());
        }
    }
}

Build and Run

bash

mvn package
java -jar target/imdb-api-client-1.0-SNAPSHOT.jar

One-off Python Request

For Python scripts using boto3.

Install Dependency

bash

pip install boto3

Create Query File (`titanic_ratings_query.graphql`)

graphql

{
  title(id: "tt0120338") {
    titleText {
      text
    }
    ratingsSummary {
      aggregateRating
      voteCount
    }
    releaseYear {
      year
    }
  }
}

Create Request Script (`imdb_api_request.py`)

python

import boto3
import json
import os

def call_imdb_api(query: str) -> dict:
    client = boto3.client(
        'dataexchange',
        region_name='us-east-1'
    )

    response = client.send_api_asset(
        DataSetId=os.environ['IMDB_DATA_SET_ID'],
        RevisionId=os.environ['IMDB_REVISION_ID'],
        AssetId=os.environ['IMDB_ASSET_ID'],
        Method='POST',
        Path='/',
        RequestHeaders={
            'Content-Type': 'application/graphql',
            'x-api-key': os.environ['IMDB_API_KEY'],
        },
        Body=json.dumps({'query': query})
    )

    return json.loads(response['Body'])


if __name__ == '__main__':
    with open('titanic_ratings_query.graphql', 'r') as f:
        query = f.read()

    result = call_imdb_api(query)
    print(json.dumps(result, indent=2))

Run

bash

export IMDB_DATA_SET_ID=your-data-set-id
export IMDB_REVISION_ID=your-revision-id
export IMDB_ASSET_ID=your-asset-id
export IMDB_API_KEY=your-api-key

python imdb_api_request.py

The script reads the GraphQL query from the file, signs the request using boto3's default credential chain (which will use the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or any configured AWS profile), and prints the formatted JSON response.

Calling the API ​

AWS CLI ​

Example 1 — Simple Rating Query (Titanic) ​

Example 2 — Complex Query (The Matrix — title, ratings, first 10 cast) ​

Postman ​

Step 1 — Create a New POST Request ​

Step 2 — Authorization Tab ​

Step 3 — Body Tab ​

Step 4 — Headers Tab ​

Expected Response ​

GraphQL Playground (TypeScript Proxy) ​

Setup ​

Proxy Script (imdb_playground_proxy_script.ts) ​

Run ​

Sample Query to Try ​

One-off TypeScript Request ​

Create the Query File (titanicRatingsQuery.graphql) ​

Create the Request Script (imdb_api_request.ts) ​

Run ​

One-off Java Request ​

Maven Project Setup ​

pom.xml ​

App.java ​

Build and Run ​

One-off Python Request ​

Install Dependency ​

Create Query File (titanic_ratings_query.graphql) ​

Create Request Script (imdb_api_request.py) ​

Run ​

Calling the API

AWS CLI

Example 1 — Simple Rating Query (Titanic)

Example 2 — Complex Query (The Matrix — title, ratings, first 10 cast)

Postman

Step 1 — Create a New POST Request

Step 2 — Authorization Tab

Step 3 — Body Tab

Step 4 — Headers Tab

Expected Response

GraphQL Playground (TypeScript Proxy)

Setup

Proxy Script (`imdb_playground_proxy_script.ts`)

Run

Sample Query to Try

One-off TypeScript Request

Create the Query File (`titanicRatingsQuery.graphql`)

Create the Request Script (`imdb_api_request.ts`)

Run

One-off Java Request

Maven Project Setup

`pom.xml`

`App.java`

Build and Run

One-off Python Request

Install Dependency

Create Query File (`titanic_ratings_query.graphql`)

Create Request Script (`imdb_api_request.py`)

Run