API Reference
The following sections detail each query and mutation and GraphQL type in the Movies API.
Queries
hello Query
Type: String
Description: The hello query is a simple hello world query to test the GraphQL setup.
Returns
Returns "Hello, GraphQL!"
Example Request and Response
REQUEST:
query {
hello
}
RESPONSE:
{
"data": {
"hello": "Hello, GraphQL!"
}
}
movies Query
Type: Movie
Description: The movies query fetches a list of movies.
Arguments
The following sections describe the arguments of the movies query.
limit
Type: Int
Default: 20
Maximum: 100
Description: Used for pagination in conjunction with offset. Number of movie records to return in the result set. Must be a non-negative value.
offset
Type: Int
Default: 0
Description: Used for pagination in conjunction with limit. Starting point for the result set. Indicates the number of records to skip or bypass from the beginning of the full result set. For example, with limit: 20 and offset: 0, you will get records 1-20. With limit: 20 and offset: 20 you will get records 21-40. Must be a non-negative value.
Returns
Returns a list of Movie objects.
Example Request and Response
REQUEST:
query {
movies(limit: 1, offset: 10) {
id
title
budget
homepage
overview
popularity
releaseDate
revenue
runtime
movieStatus
tagline
votesAvg
votesCount
cast {
actor {
id
name
}
character
}
crew {
person {
id
name
}
department
job
}
}
}
RESPONSE:
{
"data": {
"movies": [
{
"id": "24",
"title": "Kill Bill: Vol. 1",
"budget": 30000000,
"homepage": "http://www.miramax.com/movie/kill-bill-volume-1/",
"overview": "An assassin is shot at the altar by her ruthless employer, Bill and other members of their assassination circle – but 'The Bride' lives to plot her vengeance. Setting out for some payback, she makes a death list and hunts down those who wronged her, saving Bill for last.",
"popularity": 79.754966,
"releaseDate": "2003-10-10",
"revenue": 180949000,
"runtime": 111,
"movieStatus": "Released",
"tagline": "Go for the kill.",
"votesAvg": 7.7,
"votesCount": 4949,
"cast": [
{
"actor": {
"id": "3928"
"name": "Uma Thurman"
},
"character": "Beatrix 'The Bride' Kiddo"
},
{
"actor": {
"id": "5346"
"name": "Lucy Liu"
},
"character": "O-Ren Ishii"
},
# Additional cast members
],
"crew": [
{
"person": {
"id": "6197"
"name": "Bruce Del Castillo"
},
"department": "Camera",
"job": "Grip"
},
{
"person": {
"id": "5680"
"name": "Jamie Felz"
},
"department": "Camera",
"job": "First Assistant Camera"
},
# Additional crew members
]
}
]
}
}
moviesByGenre Query
Type: Movie
Description: The moviesByGenre query fetches a list of movies in the genre specified.
Arguments
The following sections describe the fields in the moviesByGenre query.
limit
Type: Int
Default: 20
Maximum: 100
Description: Used for pagination in conjunction with offset. Number of movie records to return in the result set. Must be a non-negative value.
offset
Type: Int
Default: 0
Description: Used for pagination in conjunction with limit. Starting point for the result set. Indicates the number of records to skip or bypass from the beginning of the full result set. For example, with limit: 20 and offset: 0, you will get records 1-20. With limit: 20 and offset: 20 you will get records 21-40. Must be a non-negative value.
genre
Type: String!, Required
Description: A specific type of movie, like Action or Comedy. Must be a valid genre.
Valid Genres
The following are the valid string values for the genre argument.
ActionAdventureAnimationComedyCrimeDocumentaryDramaFamilyFantasyForeignHistoryHorrorMusicMysteryRomanceScience FictionThrillerTV MovieWarWestern
Returns
Returns a list of Movie objects.
Example Request and Response
REQUEST:
query {
moviesByGenre(limit: 1, offset: 0, genre: "Action") {
id
title
budget
homepage
overview
popularity
releaseDate
revenue
runtime
movieStatus
tagline
votesAvg
votesCount
cast {
actor {
id
name
}
character
}
crew {
person {
id
name
}
department
job
}
}
}
RESPONSE:
{
"data": {
"moviesByGenre": [
{
"id": "11",
"title": "Star Wars",
"budget": 11000000,
"homepage": "http://www.starwars.com/films/star-wars-episode-iv-a-new-hope",
"overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to rescue the beautiful princess and restore peace and justice in the Empire.",
"popularity": 126.393695,
"releaseDate": "1977-05-25",
"revenue": 775398007,
"runtime": 121,
"movieStatus": "Released",
"tagline": "A long time ago in a galaxy far, far away...",
"votesAvg": 8.1,
"votesCount": 6624,
"cast": [
{
"actor": {
"id": "25"
"name": "Mark Hamill"
},
"character": "Luke Skywalker"
},
{
"actor": {
"id": "32"
"name": "Harrison Ford"
},
"character": "Han Solo"
},
# Additional cast members
],
"crew": [
{
"person": {
"id": "156"
"name": "Gilbert Taylor"
},
"department": "Camera",
"job": "Director of Photography"
},
{
"person": {
"id": "76"
"name": "George Lucas"
},
"department": "Directing",
"job": "Director"
},
# Additional crew members
]
}
]
}
}
moviesByTitle Query
Type: Movie
Description: The moviesByTitle query fetches a list of movies of the title requested.
Arguments
The following sections describe the arguments of the moviesByTitle query.
limit
Type: Int
Default: 20
Maximum: 100
Description: Used for pagination in conjunction with offset. Number of movie records to return in the result set. Must be a non-negative value.
offset
Type: Int
Default: 0
Description: Used for pagination in conjunction with limit. Starting point for the result set. Indicates the number of records to skip or bypass from the beginning of the full result set. For example, with limit: 20 and offset: 0, you will get records 1-20. With limit: 20 and offset: 20 you will get records 21-40. Must be a non-negative value.
title
Type: String!, Required
Description: Title of the movie on which you want data.
Returns
Returns a list of Movie objects.
Example Request and Response
REQUEST:
query {
moviesByTitle(limit: 5, offset: 0, title: "Forrest Gump") {
id
title
budget
homepage
overview
popularity
releaseDate
revenue
runtime
movieStatus
tagline
votesAvg
votesCount
cast {
actor {
id
name
}
character
}
crew {
person {
id
name
}
department
job
}
}
}
RESPONSE:
{
"data": {
"moviesByTitle": [
{
"id": "13",
"title": "Forrest Gump",
"budget": 55000000,
"homepage": "",
"overview": "A man with a low IQ has accomplished great things in his life and been present during significant historic events - in each case, far exceeding what anyone imagined he could do. Yet, despite all the things he has attained, his one true love eludes him. 'Forrest Gump' is the story of a man who rose above his challenges, and who proved that determination, courage, and love are more important than ability.",
"popularity": 138.133331,
"releaseDate": "1994-07-06",
"revenue": 677945399,
"runtime": 142,
"movieStatus": "Released",
"tagline": "The world will never be the same, once you've seen it through the eyes of Forrest Gump.",
"votesAvg": 8.2,
"votesCount": 7927,
"cast": [
{
"actor": {
"id": "6623"
"name": "Tom Hanks"
},
"character": "Forrest Gump"
},
{
"actor": {
"id": "7041"
"name": "Robin Wright"
},
"character": "Jenny Curran"
},
# Additional cast members
],
"crew": [
{
"person": {
"id": "7458"
"name": "Bobby Mancuso"
},
"department": "Camera",
"job": "Additional Photography"
},
{
"person": {
"id": "7325"
"name": "Phillip V. Caruso"
},
"department": "Camera",
"job": "Still Photographer"
},
# Additional crew members
]
}
]
}
}
people Query
Type: String
Description: The people query fetches a list of cast members and crew members by name, using LIKE.
Arguments
The following sections describe the arguments of the people query.
name
Type: String!, Required
Description: The name of the person to search for. For example, if name is set to Tom, the query returns all persons with tom in the name field.
limit
Type: Int
Default: 20
Maximum: 100
Description: Used for pagination in conjunction with offset. Number of movie records to return in the result set. Must be a non-negative value.
offset
Type: Int
Default: 0
Description: Used for pagination in conjunction with limit. Starting point for the result set. Indicates the number of records to skip or bypass from the beginning of the full result set. For example, with limit: 20 and offset: 0, you will get records 1-20. With limit: 20 and offset: 20 you will get records 21-40. Must be a non-negative value.
Returns
Returns a list of Person objects.
Example Request and Response
REQUEST:
query {
people(name: "Tom", limit: 2, offset: 0) {
name
id
}
}
RESPONSE:
{
"data": {
"people": [
{
"name": "Tom Hanks",
"id": "31"
},
{
"name": "Michael Winterbottom",
"id": "172"
}
]
}
}
Mutations
createMovie Mutation
Creates a new movie.
Arguments
The following sections describe the createMovie arguments.
title
Type: String!, Required
Description: Title of the movie.
budget
Type: Int
Description: The movie's budget in US dollars (USD).
homepage
Type: String
Description: The official homepage URL (Uniform Resource Locator) of the movie.
overview
Type: String
Description: A brief summary or plot overview of the movie.
popularity
Type: Float
Description: A popularity score for the movie, often based on views, ratings, and other engagement metrics.
releaseDate
Type: String
Description: The release date of the movie, formatted as YYYY-MM-DD (ISO 8601 format).
revenue
Type: Int
Description: The movie's worldwide gross revenue in US dollars (USD).
runtime
Type: Int
Description: The runtime of the movie, expressed in minutes.
movieStatus
Type: String
Description: The production status of the movie. Common values include "Released", "Rumored", "In Production", "Post Production", etc.
tagline
Type: String
Description: The movie's tagline or promotional slogan, if available.
votesAvg
Type: Float
Description: The average rating of the movie based on user votes. The rating scale is typically from 0 to 10.
votesCount
Type: Int
Description: The total number of votes the movie has received.
Returns
Returns a Movie object.
Example Request and Response
REQUEST:
mutation AddNewMovie {
createMovie(
title: "Test Movie 1",
budget: 5000000,
homepage: "https://testmovie.com",
overview: "Test Movie 1 overview",
popularity: 137.86,
releaseDate: "2024-12-05",
revenue: 10000000,
runtime: 237,
movieStatus: "Released",
tagline: "Test Movie 1 tagline",
votesAvg: 2.50,
votesCount: 522
) {
id
title
budget
homepage
overview
popularity
releaseDate
revenue
runtime
movieStatus
tagline
votesAvg
votesCount
}
}
RESPONSE:
{
"data": {
"createMovie": {
"id": "459489",
"title": "Test Movie 1",
"budget": 5000000,
"homepage": "https://testmovie.com",
"overview": "Test Movie 1 overview",
"popularity": 13786,
"releaseDate": "2024-12-05",
"revenue": 10000000,
"runtime": 237,
"movieStatus": "Released",
"tagline": "Test Movie 1 tagline",
"votesAvg": 2.5,
"votesCount": 522
}
}
}
addMovieCast Mutation
Adds the movie cast to a specified movie.
Arguments
The following sections describes the addMovieCast arguments.
movieId
Type: ID! (Non-Nullable), Required
Description: The unique identifier (ID) of the movie to which you want to add cast members. This must be a valid movie ID that already exists in the system.
castMembers
Type: [CastMemberInput!]!, Required
Description: A list of cast members to be added to the movie. This argument accepts an array of CastMemberInput objects. Each object in the array represents a single cast member and must conform to the structure defined by the CastMemberInput type. You must provide at least one CastMemberInput object in this list.
Returns
Returns a MutationResult object.
Example Request and Response
REQUEST:
mutation AddCastToMovie {
addMovieCast(
movieId: "459489"
castMembers: [
{
personId: "1893242"
characterName: "Chris Weller"
characterGender: 1
castOrder: 0
},
{
personId: "1893243"
characterName: "Bob Gart"
characterGender: 2
castOrder: 1
}
]
) {
movieId
success
}
}
RESPONSE:
{
"data": {
"addMovieCast": {
"movieId": "459489",
"success": true
}
}
}
addMovieCrew Mutation
Adds the movie crew to a specified movie.
Arguments
The following sections describes the addMovieCrew arguments.
movieId
Type: ID! (Non-Nullable), Required
Description: The unique identifier (ID) of the movie to which you want to add crew members. This must be a valid movie ID that already exists in the system.
crewMembers
Type: [CrewMemberInput!]!, Required
Description: A list of crew members to be added to the movie. This argument accepts an array of CrewMemberInput objects. Each object in the array represents a single crew member and must conform to the structure defined by the CrewMemberInput type. You must provide at least one CrewMemberInput object in this list.
Returns
Returns a MutationResult object.
Example Request and Response
REQUEST:
mutation AddCrewToMovie {
addMovieCrew(
movieId: "459489"
crewMembers: [
{
personId: "1893240"
department: "Directing"
job: "Director"
},
{
personId: "1893241"
department: "Directing"
job: "Co-director"
}
]
) {
movieId
success
}
}
RESPONSE:
{
"data": {
"addMovieCrew": {
"movieId": "459489",
"success": true
}
}
}
Types
CastMember Type
Description: Represents a single cast member's role in a movie. Each CastMember object links an actor to a specific character they played in the movie. The following section describes the fields in the CastMember type.
Fields
actor
Type: Person! (Non-Null Person Type)
Description: Information about the actor who is part of the cast. This field returns a Person object containing details about the actor, such as their unique identifier (ID) in the system and name. This field is non-nullable, meaning every CastMember will always have associated actor information.
character
Type: String
Description: The name of the character played by the actor in this movie. This string represents the fictional character within the movie's story that the actor portrayed.
CastMemberInput Type
Description: Represents the input structure for defining a single cast member to be added to a movie. This type is used within the castMembers list argument of the addMovieCast mutation.
Fields
The following sections describe the fields within the CastMemberInput type.
personId
Type: ID!, Required
Description: The unique identifier (ID) of the person who is part of the cast. This must be a valid person ID that already exists in the system.
characterName
Type: String!, Required
Description: The name of the character the cast member played in the movie.
characterGender
Type: Int
Description: The gender of the character played by the cast member. The following are the valid values for gender:
| Value | Description |
|---|---|
0 |
Unspecified |
1 |
Female |
2 |
Male |
castOrder
Type: Int
Description: The order of prominence in the movie of the cast member, starting with 0 for lead actor or actress.
CrewMember Type
Description: Represents a single crew member's occupation in a movie. Each CrewMember object links a crew member to a specific occupation in the movie. The following section describes the fields in the CrewMember type.
Fields
person
Type: Person! (Non-Null Person Type)
Description: Information about the person who is part of the crew. This field returns a Person object containing details about the crew member, such as their unique identifier (ID) and name. This field is non-nullable, meaning every CrewMember will always have associated person information.
job
Type: String
Description: The job title of the crew member.
department
Type: String
Description: The department under which the crew member performed his or her duties.
CrewMemberInput Type
Description: Represents the input structure for defining a single crew member to be added to a movie. This type is used within the crewMembers list argument of the addMovieCrew mutation.
Fields
The following sections describe the fields within the CrewMemberInput type.
personId
Type: ID!, Required
Description: The unique identifier (ID) of the person who is part of the crew. This must be a valid person ID that already exists in the system.
job
Type: String!, Required
Description: The job title of this crew member on the movie. Examples include "Director", "Composer", "Editor", "Production Designer", etc. This should be a descriptive string representing the crew member's role.
department
Type: String
Description: The department this crew member belongs to. Refer to the Valid Departments section below for a list of acceptable department names. While this field is technically optional in the CrewMemberInput type definition (in terms of GraphQL's nullability), it is highly recommended to provide a valid department for clarity and data organization. If omitted, the department might be categorized as "Unspecified" or similar in the system.
Valid Departments
The following are the valid string values for the department field in the CrewMemberInput type. Use these exact names when specifying the department for a crew member:
CameraDirectingProductionWritingEditingSoundArtCostume & Make-UpCrewVisual EffectsLightingActors
Movie Type
Description: Represents a movie in the system.
Fields
The following sections describe the fields in the Movie type.
id
Type: ID! (Non-Null Identifier)
Description: The unique identifier (ID) of the movie. This is a non-nullable field, meaning it will always have a value.
title
Type: String
Description: The title of the movie.
budget
Type: Int
Description: The movie's budget in US dollars (USD).
homepage
Type: String
Description: The official homepage URL (Uniform Resource Locator) of the movie.
overview
Type: String
Description: A brief summary or plot overview of the movie.
popularity
Type: Float
Description: A popularity score for the movie, often based on views, ratings, and other engagement metrics.
releaseDate
Type: String
Description: The release date of the movie, formatted as YYYY-MM-DD (ISO 8601 format).
revenue
Type: Int
Description: The movie's worldwide gross revenue in US dollars (USD).
runtime
Type: Int
Description: The runtime of the movie, expressed in minutes.
movieStatus
Type: String
Description: The production status of the movie. Common values include "Released", "Rumored", "In Production", "Post Production", etc.
tagline
Type: String
Description: The movie's tagline or promotional slogan, if available.
votesAvg
Type: Float
Description: The average rating of the movie based on user votes. The rating scale is typically from 0 to 10.
votesCount
Type: Int
Description: The total number of votes the movie has received.
cast
Type: [CastMember] (Non-Null List of Non-Null CastMember Types)
Description: A list of cast members who appeared in the movie. This field returns an array where each element is a CastMember object. Each CastMember in the list provides information about an actor and the specific character they portrayed in this movie. If a movie has no cast information available, this field will return an empty list (but never null).
crew
Type: [CrewMember] (Non-Null List of Non-Null CrewMember Types)
Description: A list of this movie's crew. This field returns an array where each element is a CrewMember object. Each CrewMember in the list provides information about a crew member, including job title and department. If a movie has no crew information available, this field will return an empty list (but never null).
MutationResult Type
Description: Indicates the success or failure of the addMovieCast and addMovieCrew mutations.
Fields
The following sections describe the fields in the MutationResult type.
movieId
Type: ID! (Non-Null Identifier)
Description: The unique identifier (ID) of the movie associated with the mutation.
success
Type: Boolean
Description: Indicates whether the mutation was successful (true) or unsuccessful (false).
Person Type
Description: Represents a person associated with one or more movies. The following sections describe the fields in the Person type.
Fields
id
Type: ID! (Non-Null Identifier)
Description: The persons's unique identifier (ID) in the system.
name
Type: String! (Non-Null)
Description: The persons's full name.
HTTP Response Codes
200 OK
A 200 OK status code means the API received the client's request and provided a response, whether the response includes data or error details. For example, if a people query does not include the required name argument, although the HTTP response code would be 200 OK,the response would look like this:
{
"errors": [
{
"message": "Field \"people\" argument \"name\" of type \"String!\" is required but not provided.",
"locations": [
{
"line": 6,
"column": 3
}
]
}
]
}
401 Unauthorized
A 401 Unauthorized status code means the client failed authentication. Either the API key was not provided or was not valid. Please refer to the Getting Started section for instructions to get and use a valid API key.
403 Forbidden
A 403 Forbidden status code means the client does not have the permissions required to access the requested mutation. Please refer to the Getting Started section for instructions to get and use a valid API key.
500 Internal Server Error
A 500 Internal Server Error status code means that something went wrong on the server side. Please contact the API owner for assistance.
Exploring the API Schema with Introspection
The Movies API, being a GraphQL API, is self-documenting and introspectable. You can query the schema to learn:
- what data is available.
- the queries and mutations you can perform.
- the fields, data types, and descriptions.
The schema is not just static documentation but is also programmatically accessible through the API endpoint.
How to Perform an Introspection Query
To perform introspection, you use a special query called an "introspection query". The following is the standard introspection query. Send this query to the Movies API endpoint just like any other GraphQL query.
query FullIntrospectionQuery {
__schema { # Root field for introspection, allowing access to schema-level information.
queryType { name } # Fetches the name of the root query type.
mutationType { name } # Fetches the name of the root mutation type.
subscriptionType { name } # Fetches the name of the root subscription type.
types { # Fetches a list of all types defined in the schema.
...FullType # Retrieves detailed information about each type.
}
directives { # Fetches information about directives defined in the schema.
name
description
locations
args {
...InputValue
}
}
}
}
fragment FullType on __Type { # Defines what information to fetch for each type.
kind # The kind of type (e.g., "OBJECT", "INTERFACE", "ENUM", "SCALAR", "INPUT_OBJECT").
name
description
specifiedByURL # GraphQL spec 2021 onwards.
fields(includeDeprecated: true) {
name
description
args {
...InputValue
}
type {
...TypeRef
}
isDeprecated
deprecationReason
}
inputFields {
...InputValue
}
interfaces {
...TypeRef
}
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes { # For UNION and INTERFACE types, fetches possible member types using TypeRef.
...TypeRef
}
}
fragment InputValue on __InputValue { # Defines what information to fetch for input values.
name
description
type { ...TypeRef }
defaultValue
isDeprecated
deprecationReason
}
fragment TypeRef on __Type { # Recursive fragment for handling nested types, seven levels.
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
}
}
Note about the Full Introspection Query Response
This is the standard, comprehensive GraphQL introspection query. When you execute this query against the Movies API endpoint, you might notice that some parts of the response are null or empty lists. This is perfectly normal and depends on the features implemented in a specific GraphQL API.
For example:
subscriptionType { name }: If an API does not implement GraphQL Subscriptions (as is the case with the current Movies API example), thesubscriptionTypefield in the response will likely benull. This simply indicates that the API does not offer real-time subscriptions.directives { ... }: If a schema does not define any custom GraphQL directives, thedirectiveslist in the response might be empty.
Client tools and libraries that use introspection are designed to handle these potentially null or empty responses gracefully. They will correctly interpret the schema based on the information that is present in the introspection result.
The important takeaway is that this full query provides a complete picture of what a GraphQL schema can contain, and the response will accurately reflect the features that are and are not implemented in your API.
Introspection with Altair GraphQL Client
If you are using Altair GraphQL Client, introspection is simple.
- Connect to the API Endpoint: Enter the Movies API GraphQL endpoint URL in Altair and click "Connect to Server".
- Automatic Introspection: Altair will usually automatically perform an introspection query as soon as you connect.
- Document Explorer: Look for the schema information on the left-hand side in Altair. You'll see:
- Queries: A list of all available queries.
- Mutations: A list of all available mutations.
- Types: A comprehensive list of all the Object Types, Input Types, Enums, etc., defined in your API schema.
Introspection in Client Applications and Tools
Beyond interactive tools like Altair, introspection is fundamental to how many GraphQL client libraries and development tools work:
-
Client Libraries (e.g., Apollo Client, Relay): GraphQL client libraries often use introspection to:
- Fetch the schema: When your application starts, the client library might automatically send an introspection query to download the schema from the API.
- Query Validation: The client library can then use the schema to validate your GraphQL queries before sending them to the server, catching errors early in development.
- Type Generation: Some tools and libraries can generate code (like TypeScript types or Flow types) automatically from the schema, improving type safety in your frontend code.
-
Schema Visualization Tools: There are tools that take introspection output and generate visual diagrams of your GraphQL schema, making it easier to understand complex API structures. GraphQL Editor (Commercial, Web-Based & Desktop App) and GraphQL Voyager (Free, Web-Based) are examples.
-
Documentation Generators: Some documentation generators can consume introspection data to automatically create API documentation websites, ensuring that documentation stays up-to-date with schema changes.
-
Programmatic Introspection: You can also send introspection queries directly from your own code (using HTTP clients or GraphQL client libraries) if you need to programmatically access schema information.