Transitioning from REST APIs

If you’re currently using Udacity’s REST APIs, this guide will help you understand how to migrate to the new GraphQL-based Public API.

Why migrate?

	REST APIs	GraphQL Public API
Documentation	Scattered across multiple sources	Centralized on `develop.udacity.com`
Authentication	Varies by endpoint	Unified `Authorization: Token`
Data fetching	Fixed response shapes, often over-fetching	Request exactly what you need
Playground	None	Interactive GraphiQL for every domain
Rate limiting	Inconsistent	Standardized with clear headers
Pagination	Varies (offset, page-based)	Consistent cursor-based pagination
Combined queries	Multiple requests needed	Single request for multiple resources

REST API → GraphQL mapping

Legacy REST API	GraphQL Replacement	Status	Key Changes
Catalog API	Catalog API	Available	Duration format, field naming, includes assessments and learning plans
Learner Progress API v2	Program Progress + Assessment Progress + Learning Plan Progress	Available	Cursor pagination, unified structure
Data API	Program Progress, Assessment Progress, Learning Plan Progress	Available	Progress APIs cover most use cases

Migration guides

Catalog API Migration

Complete guide for migrating from GET /api/emc/companies/{id}/catalog to the GraphQL Catalog API. Includes step-by-step instructions, field mapping, duration format conversion, and testing guidance.

Learner Progress API v2 Migration

Guide for migrating learner progress and enrollment data to the Program Progress, Assessment Progress, and Learning Plan Progress APIs.

Data API Migration

Guide for migrating data export functionality to the GraphQL API.

General migration steps

1. Generate API credentials

If you don’t already have one, generate API credentials in Manage Web.

2. Update authentication

Before (Catalog REST):

curl -H "X-Auth-Token: YOUR_TOKEN" \
  https://api.udacity.com/api/emc/companies/123/catalog

After (All GraphQL APIs):

curl -X POST https://api.udacity.com/api/public/api/v1/catalog/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_KEY" \
  -d '{"query": "{ catalog { programs { key title } } }"}'

3. Replace REST calls with GraphQL queries

Before (REST):

curl -H "X-Auth-Token: $TOKEN" \
  https://api.udacity.com/api/emc/companies/123/catalog

After (GraphQL):

query {
  catalog {
    programs {
      key
      title
      type
      summary
      duration
      imageUrl
      redirectUrl
    }
    assessments {
      id
      title
      category
      isTimed
    }
  }
}

4. Update field naming

Most REST APIs use snake_case while GraphQL uses camelCase:

REST	GraphQL
`image_url`	`imageUrl`
`redirect_url`	`redirectUrl`
`syllabus_url`	`syllabusUrl`
`modified_date`	`modifiedDate`
`user_id`	`userId`
`first_name`	`firstName`
`created_at`	`createdAt`

5. Handle data format changes

Duration format (Catalog API) — Breaking Change:

Before (REST):

{ "duration": 102240, "duration_type": "minutes" }

After (GraphQL):

{ "duration": "P71D" }

6. Update response parsing

REST response structure:

{ "programs": [ ... ] }

GraphQL response structure:

{ "data": { "catalog": { "programs": [ ... ] } } }

7. Update error handling

GraphQL APIs return errors in a standardized format:

{
  "errors": [
    {
      "message": "Unauthorized: invalid or missing token",
      "extensions": { "code": "UNAUTHENTICATED" }
    }
  ],
  "data": null
}

Always check for the errors array in GraphQL responses. See Error Handling.

Migration best practices

Start small — Migrate one integration at a time
Test in parallel — Run both REST and GraphQL implementations side-by-side
Use the Playground — Test your GraphQL queries in the Playground before implementing
Monitor closely — Watch for errors and performance changes
Keep a rollback plan — Maintain your REST implementation until migration is stable

Need help?

Use the Playground to experiment with queries
Read detailed guides for each API
Contact your Udacity account team for migration assistance