Explore GraphQL APIs explore-graphql-apis

From the AEM Start screen, navigate to Tools > General > GraphQL.

Tap Create in the top-right corner, in the resulting dialog enter the following values:

• Name*: My Project Endpoint.
• Use GraphQL schema provided by … *: My Project

Tap Create to save the endpoint.

The GraphQL endpoints created based on a project configuration only enable queries against models belonging to that project. In this case, the only queries against the Person and Team models can be used.

You should now see one GraphQL endpoint enabled on your environment.

From the AEM Start screen, navigate to Tools > General > GraphQL Query Editor.

In the top-right corner, make sure that the Endpoint is set to My Project Endpoint.

Paste the following query in the main panel (replacing the list of comments):

query allTeams {
  teamList {
    items {
      _path
      title
    }
  }
}

Press the Play button in the top menu to execute the query. You should see the results of the content fragments from the previous chapter:

Position the cursor beneath the title text and enter CTRL+Space to trigger code hinting. Add shortname and description to the query.

Execute the query again by pressing the Play button and you should see that the results include the additional properties of shortname and description.

The shortname is a simple property and description is a multi-line text field and the GraphQL API allows us to choose various formats for the results like html, markdown, json, or plaintext.

Update the query to include the teamMembers property. Recall that this is a Fragment Reference field to the Person Model. Properties of the Person model can be returned:

query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

JSON Response:

{
    "data": {
        "teamList": {
        "items": [
            {
            "_path": "/content/dam/my-project/en/team-alpha",
            "title": "Team Alpha",
            "shortName": "team-alpha",
            "description": {
                "plaintext": "This is a description of Team Alpha!"
            },
            "teamMembers": [
                {
                "fullName": "John Doe",
                "occupation": [
                    "Artist",
                    "Influencer"
                ]
                },
                {
                "fullName": "Alison Smith",
                "occupation": [
                    "Photographer"
                ]
                }
              ]
        }
        ]
        }
    }
}

The ability to query against nested fragments is a powerful feature of the AEM GraphQL API. In this simple example, the nesting is only two levels deep. However it’s possible to nest fragments even further. For example, if there was an Address model associated with a Person it would be possible to return data from all three models in a single query.

Enter the following query in the GraphiQL UI:

query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
    }
  }
}

The above query performs a search against all Person fragments in the system. The added filter to the beginning of the query performs a comparison on the name field and the variable string $name.

In the Query Variables panel enter the following:

{"name": "John Doe"}

Execute the query, it is expected that only Persons Content Fragment is returned with a value of John Doe.

There are many other options for filtering and creating complex queries, see Learning to use GraphQL with AEM - Sample Content and Queries.

Enhance above query to fetch profile picture

query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
      profilePicture{
        ... on ImageRef{
          _path
          _authorUrl
          _publishUrl
          height
          width

        }
      }
    }
  }
}

The profilePicture is a content reference and it is expected to be an image, therefore built-in ImageRef object is used. This allows us to request additional data about the image being reference, like the width and height.

Enter the following query in the GraphiQL editor:

query personByPath($path: String!) {
    personByPath(_path: $path) {
        item {
        fullName
        occupation
        }
    }
}

Enter the following for the Query Variables:

{"path": "/content/dam/my-project/en/alison-smith"}

Execute the query and observe that the single result is returned.

Enter the following query in the GraphiQL IDE:

query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

Verify that the query works.

Next tap Save As and enter all-teams as the Query Name.

The query should be shown under Persisted Queries in the left rail.

Next tap the ellipses … next to the persistent query and tap Copy URL to copy the path to your clipboard.

Open a new tab and paste the copied path in your browser:

https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams

It should look similar to the above path. You should see that the JSON results of the query returned.

Breaking down the above URL:

Return to the GraphiQL IDE and use the plus button + to persist the NEW query

query personByName($name: String!) {
  personList(
    filter: {
      fullName:{
        _expressions: [{
          value: $name
          _operator:EQUALS
        }]
      }
    }){
    items {
      _path
      fullName
      occupation
      biographyText {
        json
      }
      profilePicture {
        ... on ImageRef {
          _path
          _authorUrl
          _publishUrl
          width
          height
        }
      }
    }
  }
}

Save the query as: person-by-name.

You should have two persisted queries saved:

From the AEM Start screen, navigate to Tools > General > GraphQL.

Tap the checkbox next to My Project Endpoint and tap Publish

From the AEM Start screen, navigate to Tools > General > GraphQL Query Editor

Tap the all-teams query from Persisted Queries panel and tap Publish

Repeat above step for person-by-name query