Migrating from REST to GraphQL APIs

Tags: Skills

Pluralsight Skills' APIs provide the most efficient way to unlock Skills data and extend the platform into your internal systems and workflows. Skills' newest APIs are powered by GraphQL, a technology that gives you exactly what you need intuitively and efficiently.

Who can use this?

 StndPremStrtProEnt
Learners:     
Managers:     
Admins:  

 

While Skills' previous REST APIs offered a limited dataset focused on courses, usage, and user management, GraphQL APIs expand the datasets to channels, roles, skills, and more. GraphQL also allows you to replace multiple REST queries with a single query which includes explicit data requirements. This article contains sample code and developer resources that will help you migrate from REST to GraphQL.


How GraphQL differs from REST

A single GraphQL query can fetch the complete array of data per the relationships defined in the schema, instead of multiple requests with REST.

GraphQL also allows for mutations, allowing you to perform, create, update, and delete operations, thereby replacing CRUD functionality in REST APIs.

GraphQL has a greater number of API fields available, and queries are simpler and more precise. See the complete Skills GraphQL Schema within the Developer Portal (opens in new tab) for fields and definitions.

back to top


Migrating from REST to GraphQL

As a plan admin, you have the ability to use GraphQL APIs, create API keys, and submit queries. You also have access to the Developer Portal (opens in new tab), the primary developer resource for working with our APIs. If you’re unsure whether you have plan admin permissions, visit Manage Keys (opens in new tab) to see if you can create a new GraphQL API key.

Tip: If you’re a developer or analyst, you can still obtain data through APIs by having your plan admin generate and share their API key with you.

If you want to start fresh with GraphQL, use the Developer Portal to complete these steps:

  1. Generate an API key (opens in new tab).

  2. Learn how to build your First GraphQL API Query (opens in new tab).

  3. Copy one of the sample code snippets from the tables below to begin testing your Queries in the built-in Playground (opens in new tab). Consult the API documentation in the Developer Portal to add or remove fields as required.

If you'd rather modify your existing REST queries, see examples of how to modify your queries below.

Course Daily Usage API

For applicable filters for the GraphQL Content Usage API, please see courseDailyUsage (opens in new tab).

See Content usage (opens in new tab) if you're looking to migrate from the REST Content Usage API.

REST API fieldGraphQL API fieldSample code
UserIduser { id }{
    courseDailyUsage {
        nodes {
            user {
                id
                firstName
                lastName
                email
                team {
                    name
                }
                note
                isOnAccount
            }
            course {
                id
                slug
                title
            }
            rollupDate
            clipViewSeconds
        }
    }
}
FirstNameuser { firstName }
LastNameuser { lastName }
Emailuser { email }
TeamNameuser { team {name} }
Noteuser { note }
IsOnAccountuser { isOnAccount }
ContentTypeN/A
ContentIdcourse { id }
ContentSlugcourse { slug }
ContentNamecourse { title }
ViewDaterollupDate
UsageInSecondsclipViewSeconds

Filters

REST API Filter exampleGraphQL API filter exampleExample description
&startDate=2019-12-04
&endDate=2019-12-04
filter: {
    startDate: “2019-12-04”
    endDate: “2019-12-04”
}
Use this filter to pull delta reports (example daily, weekly or biweekly reports). GraphQL API is based on the field lastActivityOn. Note: There could be a 24-hour data lag, so to get data from the 24th, for example, pull data on the 26th.

User API

Use this if you're looking to migrate from the REST Users API (opens in new tab).

For applicable filters for the GraphQL Users API, please see Users (opens in new tab).

REST API fieldGraphQL API fieldSample code
UserIdid{
    users {
        nodes {
            id
            firstName
            lastName
            email
            startedOn
            note
            team {
                name
            }
        }
    }
}
Emailemail
FirstNamefirstName
LastNamelastName
StartDatestartedOn
Notenote
TeamNameteam
N/AisOnAccount
N/AremovedOn
N/AssoIdentifiers
N/AssoEnabled
N/AplanId
N/AcreatedOn
N/AadditionalEmails

Note: By default, the Users API includes all current as well as historical licensed users on the plan. Use isCurrent userFilter (opens in new tab) to extract current users only.

back to top


Content completion APIs

If you're looking to migrate from the Content Completion REST API (opens in new tab), there are two options available:

  1. CourseProgress API (opens in new tab) is currently in General Release and only provides data from Video courses (opens in new tab).
  2. ContentProgress API (opens in new tab) provides data from all content types like videos, guides, paths, interactive courses and projects. This API is currently in Beta.

Course Progress API

The GraphQL Course Progress API (opens in new tab) includes courses that are in progress.

REST API fieldGraphQL API fieldSample code
dir="ltr">UserIduser { id }{
    courseProgress {
        nodes {
            user {
                id
                firstName
                lastName
                email
                team {
                    name
                }
                note
                isOnAccount
            }
            course {
                id
                title
                slug
            }
            firstViewedClipOn
            percentComplete
            isCourseCompleted
            completedOn
        }
    }
}
FirstNameuser { firstName }
LastNameuser { lastName }
Emailuser { email }
TeamName<user { team {name} }
Noteuser { note }
IsOnAccountuser { isOnAccount }
ContentTypeN/A
ContentIdcourse { id }
ContentSlugcourse { slug }
ContentNamecourse { title }
FirstActivityDatefirstViewedClipOn
PercentCompletepercentComplete
CompletionStatusisCourseCompleted
CompletionDatecompletedOn

For applicable filters for the Course Progress API, please see Course progress filter (opens in new tab).

Content Progress API

For applicable filters for the Content Progress API (opens in new tab), please see Content progress filter (opens in new tab).

REST API fieldGraphQL API fieldSample code
UserIduser { id }{
contentProgress {
nodes {
user {
id
firstName
lastName
email
team {
name
}
note
isOnAccount
}
course {
id
title
slug
}
firstViewedClipOn
percentComplete
isCourseCompleted
completedOn
}
}
}
FirstNameuser { firstName }
LastNameuser { lastName }
Emailuser { email }
TeamNameuser { team {name} }
Noteuser { note }
IsOnAccountuser { isOnAccount }
ContentTypeContentProgressType { ContentType }
ContentIdcourse { id }
ContentSlugcourse { slug }
ContentNamecourse { title }
FirstActivityDatefirstViewedClipOn
PercentCompletepercentComplete
CompletionStatusisCourseCompleted
CompletionDatecompletedOn

Course Daily Usage API

Use the Course Daily Usage API (opens in new tab) if you're looking to migrate from the REST course usage API (opens in new tab).

For applicable filters for the GraphQL Course Daily Usage API, please see Course daily usage filter (opens in new tab).

REST API fieldGraphQL API fieldSample code
UserIduser { id }{
    courseDailyUsage {
        nodes {
            user {
                id
                firstName
                lastName
                email
                team
                    name
                }
                note
                isOnAccount
            }
            course {
                id
                slug
                title
            }
            rollupDate
            clipViewSeconds
        }
    }
}
FirstNameuser { firstName }
LastName<user { lastName }
Emailuser { email }
TeamNameuser { team {name} }
Noteuser { note }
IsOnAccountuser { isOnAccount }
ContentTypeN/A
ContentIdcourse { id }
ContentSlugcourse { slug }
ContentNamecourse { title }
ViewDaterollupDate
UsageInSecondsclipViewSeconds
CompletionStatusisCourseCompleted
CompletionDatecompletedOn

back to top


License management APIs

Member Invite API

Use the Member Invite API (opens in new tab) if you’re looking to migrate from the REST Get All Invites API (opens in new tab).

Note: The REST API returns a note field by default. If you need the same field in GraphQL, call Users API and input the redeemedByUserId value in the filter as shown in the sample code.

REST API fieldGraphQL API fieldSample code
NoneinviteId{
  memberInvites {
    nodes {
      inviteId
      planId
      sentToEmail
      teamId
      sentOn
      expiresOn
      redeemedByUserId
      status
    }
  }
}

{
  users(filter: {ids: “<Input redeemedByUserId value here>”}) {
    nodes {
      id
      note
    }
  }
}
-planId
-sentToEmail
-teamId
-user { note }
-sentOn
-expiresOn
Filters
REST API filtersGraphQL API filters
noteNot available; Pending enhancement
emailsentToEmail
teamIdNot available; Pending enhancement

The response fields available for this GraphQL API closely match the response fields from the REST API.

REST API fieldGraphQL API field
idinviteId
emailsentToEmail
teamIdteamId
noteuser { note }
sendDatesentOn
expiresOnexpiresOn

Invite Member API—Mutation or Write API

Use the Invite Member API—Mutation or Write API (opens in new tab) if you're looking to migrate from the REST Invite new user API (opens in new tab).

REST API fieldGraphQL API fieldSample code
emailemailmutation {
  inviteMember(input: {
    email: “<insert email here>”,
    teamId: <Insert teamId here>,
    note: “<Insert note here>”}) {
    inviteId
    email
    teamId
    note
  }
}
teamIdteamId
notenote

Cancel Invite—Mutation or Write API

Use the  if you’re looking to migrate from the REST Cancel invite API (opens in new tab).

REST API fieldGraphQL API fieldSample code
idinviteIdmutation {
  cancelInvite(input: {
     inviteId: “<Insert InviteID here>”}) {
       inviteId
   }
}

Users API

Use the Users API (opens in new tab) if you’re looking to migrate from the REST Get all Users API (opens in new tab).

REST API fieldGraphQL API fieldSample code
-id{
  users {
    nodes {
      id
      email
      additionalEmails
      firstName
      lastName
      startedOn
      createdOn
      note
      teams {
        edges {
          node {
            id
          }
        }
      }
      isOnAccount
      removedOn
      currentSsoIdentifier
    }
  }
}
-additionalEmails
-createdOn
-teams { id }
-firstName
-lastName
-email
-note
-startedOn
-isOnAccount
-removedOn
-currentSsoIdentifier
Filters
REST API filtersGraphQL API filters
firstNameNot available
lastNameNot available
emailemails
notenotes
teamIdNot available; Pending enhancement
Not availablessoIdentifiers
Not availableonlyCurrent
 ids

The response fields available for this GraphQL API closely match the response fields from the REST API.

REST API fieldGraphQL API field
idid
teamIdteams { id }
firstNamefirstName
lastNamelastName
emailemail
notenote

Get user by ID API

Use the Get user by ID API (opens in new tab) if you’re looking to migrate from the REST Get user by ID API (opens in new tab).

REST API fieldGraphQL API fieldSample code
-id{
  users (filter: {ids:”<Insert user ID here>”})  {
    nodes {
      id
      email
      additionalEmails
      firstName
      lastName
      startedOn
      createdOn
      note
      teams {
        edges {
          node {
            id
          }
        }
      }
      isOnAccount
      removedOn
      currentSsoIdentifier
    }
  }
}
-additionalEmails
-createdOn
-teams { id }
-firstName
-lastName
-email
-note
-startedOn
-isOnAccount
-removedOn
-currentSsoIdentifier

The response fields available for this GraphQL API closely match the response fields from the REST API.

REST API fieldGraphQL API field
idid
teamIdteams { id }
firstNamefirstName
lastNamelastName
emailemail
notenote

Edit user API—Mutation or Write API

Use the Edit user API—Mutation or Write API (opens in new tab) if you’re looking to migrate from the REST update user API (opens in new tab).

REST API fieldGraphQL API fieldSample code
teamIdUse a separate API moveMemberToTeammutation {
  editUser (input: {
   userId: “<insert user ID>”,
   firstName: “<Insert first name here>”,            
   lastName: “<insert last name>”,
   email: “<“Insert email Id here>”,
    remoteUserId: “<“Insert remote user ID here>”}) {
    userId
    firstName
    lastName
    email
    remoteUserId
  }
}
noteNot available
emailemail
Not availableuserId
Not availablefirstName
Not availablelastName
Not availableremoteUserId

Remove user API—Mutation or Write API

Use the Remove user API—Mutation or Write API (opens in new tab) if you’re looking to migrate from the REST Remove user API (opens in new tab).

REST API fieldGraphQL API fieldSample code
iduserIdmutation {
  removeUser(input:{userId:”<Insert user id here>“}){
    userId
  }
}

Teams API

Use the Teams API (opens in new tab) if you’re looking to migrate from the REST Get all teams API (opens in new tab).

REST API fieldGraphQL API fieldSample code
idid{
 teams {
  nodes{
    id
    name
    planId
    groupId
    description
  }
}
namename
Not availableplanId
Not availabledescription
Not availablegroupId
Filters
REST API filtersGraphQL API filters
namename
Not availabledescription

back to top


If you need help, please email support@pluralsight.com for 24/7 assistance.