Hands-on example: Adding the Rick and Morty GraphQL API

• The API is free and publicly accessible and does not require authentication.
• The API contains interconnected data for characters, locations, and episodes.
• The API demonstrates common GraphQL patterns, such as filtering, pagination, aliases, and nested relationships.
• You can complete the example without configuring a backend.

The GraphQL endpoint is available at: https://rickandmortyapi.com/graphql

The dataset contains information about 826+ characters, 126+ locations, and 51 episodes. You add this endpoint to API Gateway and use GraphQL Playground to explore the data.

Create a schema file for the Rick and Morty API. Save the file as rick-and-morty-schema.graphql.

type Query {
  character(id: ID!): Character
  characters(page: Int, filter: FilterCharacter): Characters
  location(id: ID!): Location
  locations(page: Int, filter: FilterLocation): Locations
  episode(id: ID!): Episode
  episodes(page: Int, filter: FilterEpisode): Episodes
}

type Character {
  id: ID!
  name: String!
  status: String!
  species: String!
  type: String!
  gender: String!
  origin: Location!
  location: Location!
  image: String!
  episode: [Episode!]!
  created: String!
}

type Characters {
  info: Info
  results: [Character]
}

type Location {
  id: ID!
  name: String!
  type: String!
  dimension: String!
  residents: [Character!]!
  created: String!
}

type Locations {
  info: Info
  results: [Location]
}

type Episode {
  id: ID!
  name: String!
  air_date: String!
  episode: String!
  characters: [Character!]!
  created: String!
}

type Episodes {
  info: Info
  results: [Episode]
}

type Info {
  count: Int
  pages: Int
  next: Int
  prev: Int
}

input FilterCharacter {
  name: String
  status: String
  species: String
  type: String
  gender: String
}

input FilterLocation {
  name: String
  type: String
  dimension: String
}

input FilterEpisode {
  name: String
  episode: String
}

Add a Non-Infor API Suite and add the Rick and Morty GraphQL endpoint.

1. Sign in to API Gateway.
2. Select Available API.
3. Create a Non-Infor API Suite.
4. Specify the suite information:
   • Application Name: Rick and Morty API
   • Suite Name: Rick and Morty API
   • Description: API Suite to test Rick and Morty GraphQL APIs
   • API Context: RAM
5. Add a new endpoint and specify:
   • Target Endpoint URL: https://rickandmortyapi.com/graphql
   • Target Endpoint Description: GraphQL API for Rick and Morty character, location, and episode data
   • Proxy Context: rickandmortyapi
   • Authentication Type: Anonymous
6. Select Save.

Add GraphQL schema documentation for the proxy endpoint.

1. Locate the proxy endpoint for the Rick and Morty API Suite.
2. Open documentation for the proxy endpoint.
3. Add documentation.
4. In the endpoint documentation section, specify:
   • Name: rickandmorty
   • Type: GraphQL Schema
   • Introspection URL: https://rickandmortyapi.com/graphql
5. Select Save.

The Rick and Morty endpoint supports schema introspection, so uploading a schema file is optional. Upload a schema file if schema retrieval is not available or does not complete successfully.

1. Select the option to upload a schema.
2. Select the rick-and-morty-schema.graphql file.
3. Verify that a schema upload confirmation message is displayed.

Open GraphQL Playground from the documentation for the proxy endpoint.

• Locate the Rick and Morty API Suite and select the proxy endpoint.
• Open documentation for the proxy endpoint to load GraphQL Playground.

The GraphQL Playground interface includes a query editor, a response viewer, and navigation items such as documentation and history.

Use the schema documentation panel to review available queries and data types.

• Open the documentation panel in GraphQL Playground.
• Review the available queries, such as character, characters, location, locations, episode, and episodes.
• Review data types such as Character, Location, and Episode.

Run a query to retrieve information for Rick Sanchez (character ID 1).

query GetRickSanchez {
  character(id: 1) {
    id
    name
    status
    species
    gender
    origin {
      name
      dimension
    }
    location {
      name
    }
    image
  }
}

Example response:

{
  "data": {
    "character": {
      "id": "1",
      "name": "Rick Sanchez",
      "status": "Alive",
      "species": "Human",
      "gender": "Male",
      "origin": {
        "name": "Earth (C-137)",
        "dimension": "Dimension C-137"
      },
      "location": {
        "name": "Citadel of Ricks"
      },
      "image": "https://rickandmortyapi.com/api/character/avatar/1.jpeg"
    }
  }
}

This query returns only the requested fields and includes nested data for origin and location.

Run a filtered query to retrieve characters that contain Morty in the name.

query SearchMortyCharacters {
  characters(filter: { name: "Morty" }) {
    info {
      count
    }
    results {
      id
      name
      status
      species
      image
    }
  }
}

The info object includes the count of matching characters.

Run a paginated query to retrieve one page of results.

query GetCharactersPage1 {
  characters(page: 1) {
    info {
      count
      pages
      next
      prev
    }
    results {
      id
      name
      species
      status
    }
  }
}

Update page to retrieve a different page of results.

Run a query that retrieves a character and the related episodes.

query GetCharacterWithEpisodes {
  character(id: 1) {
    name
    status
    episode {
      id
      name
      air_date
      episode
    }
  }
}

This query retrieves related data in a single request.

Run a query that retrieves a character, a location, and an episode in one request.

query GetDashboardData {
  mainCharacter: character(id: 1) {
    name
    status
    image
  }
  citadel: location(id: 3) {
    name
    type
    dimension
    residents {
      name
    }
  }
  pilotEpisode: episode(id: 1) {
    name
    air_date
    episode
    characters {
      name
    }
  }
}

Aliases define unique names for the returned objects.

These examples show filtering and relationship traversal.

Filter by multiple criteria

query FilterCharacters {
  characters(filter: {
    status: "Alive",
    species: "Human",
    gender: "Female"
  }) {
    info {
      count
    }
    results {
      id
      name
      origin {
        name
      }
    }
  }
}

Explore a location and its residents

query GetCitadelResidents {
  location(id: 3) {
    name
    type
    dimension
    residents {
      id
      name
      status
      species
    }
  }
}

Find episodes by season

query GetSeason1Episodes {
  episodes(filter: { episode: "S01" }) {
    results {
      id
      name
      air_date
      episode
      characters {
        name
      }
    }
  }
}

• Character directory: Use filtering and pagination to provide search results.
• Episode guide with cast: Retrieve episode details and included characters.
• Location explorer: Retrieve location details and residents.
• Character profile: Retrieve origin, current location, and episodes for a character.
• Statistics dashboard: Retrieve counts for characters, locations, and episodes.

• Use query variables for reusable queries.
• Use fragments for reusable field groups.
• Use descriptive query names.
• Use auto-completion to review available fields and arguments.
• Format queries before you run them.
• Use schema documentation to review available fields when you troubleshoot a query.

• Download the schema from the documentation for the proxy endpoint.
• Switch the documentation type if you use a different documentation format, such as OpenAPI or AsyncAPI.
• Upload an updated schema when the GraphQL schema changes.

• GraphQL Playground is available only for Non-Infor API Suites.
• Schema files must be in valid GraphQL Schema Definition Language (SDL) format.
• The maximum schema file size is determined by the API Gateway upload limit (4 MB).
• GraphQL APIs are not supported in API metadata.