Udacity LogoUdacity API

Migrating from the Catalog REST API

Step-by-step guide to migrating from the legacy REST Catalog endpoint to the new GraphQL API.

Endpoints
GET/api/emc/companies/{id}/catalog
POSThttps://api.udacity.com/api/public/api/v1/catalog/graphql
Overview

Quick summary

Auth Header

X-Auth-Token → Authorization: Token

Company ID

Was in URL path → now embedded in token scope.

Field Naming

snake_case → camelCase

Duration Format

Integer minutes → ISO8601 string (e.g., P30D).

Assessments

Not available in REST → included in GraphQL response.

Field Selection

All fields returned → request only what you need.

Step 1–2

Update endpoint and authentication

Generate API credentials in Manage Web. Your token will automatically include the COMPANY:<companyId> scope.

Before (REST)
curl -H "X-Auth-Token: YOUR_TOKEN" \
  https://api.udacity.com/api/emc/companies/123/catalog
After (GraphQL)
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 { companyId programs { key title type summary duration imageUrl redirectUrl syllabusUrl modifiedDate } } }"
  }'
Step 3–4

Field names & duration format

Field name changes (snake_case → camelCase)

image_url→ imageUrl
redirect_url→ redirectUrl
syllabus_url→ syllabusUrl
modified_date→ modifiedDate

Duration format change

Breaking Change: Duration changed from integer minutes to ISO8601 duration strings.

  • P30D = 30 days
  • P1Y2M = 1 year, 2 months
  • PT2H30M = 2 hours, 30 minutes
REST Duration
{ "duration": 102240, "duration_type": "minutes" }
GraphQL Duration
{ "duration": "P71D" }
Step 5

Update response parsing

GraphQL wraps results in data.catalog. Access programs via response.data.catalog.programs.

New fields in GraphQL

versionInt

Program version number (new).

localeString

Program locale (new).

ssoLaunchLinksByContract[SSOLink]

SSO deep links by contract (new).

assessments[Assessment]

Assessment catalog — not available in REST (new).

REST Response
{
  "programs": [
    {
      "key": "nd124-ent",
      "title": "Google AdWords Enterprise",
      "type": "DEGREE",
      "duration": 102240,
      "duration_type": "minutes",
      "image_url": "https://..."
    }
  ]
}
GraphQL Response
{
  "data": {
    "catalog": {
      "companyId": "123",
      "programs": [
        {
          "key": "nd124-ent",
          "title": "Google AdWords Enterprise",
          "type": "DEGREE",
          "duration": "P71D",
          "imageUrl": "https://...",
          "version": 1,
          "locale": "en-us"
        }
      ],
      "assessments": [ ... ]
    }
  }
}
Checklist

Migration checklist

  • Generate API credentials in Manage Web
  • Update auth header: X-Auth-Token → Authorization: Token
  • Change HTTP method: GET → POST
  • Update endpoint to https://api.udacity.com/api/public/api/v1/catalog/graphql
  • Add request body with GraphQL query as JSON
  • Add Content-Type: application/json header
  • Update field names: all snake_case → camelCase
  • Handle duration format: integer minutes → ISO8601
  • Update response parsing: access via response.data.catalog
  • Check for errors array in responses
  • Test in Playground

Related documentation