GET profile

Get an individual CDS Profile. The list of valid CDS profiles can be found here

GET /v1/profiles/{profileName}

Requires Auth?

No (open access)

Response Codes

Response Code Meaning
200 A single CDS Schema or Profile in JSON format 
{
    "$schema": "https://json-schema.org/draft/2019-09/schema#",
    "$id": "/v1/profiles/youtube-video",
    "title": "YouTube Video",
    "description": "An asset representing a YouTube video associated with a document. For more information on how to use this to construct a link/embed, see https://developers.google.com/youtube.",

    "type": "object",
    "required": [
        "videoId"
    ],
    "properties": {
        "headline": {
            "description": "The person, organization, or series associated with this video for attribution purposes",
            "type": "string"
        },
        "subheadline": {
            "description": "The caption used for the embedded video link",
            "type": "string"
        },
        "startTime": {
            "description": "Number of seconds in the video to start playback",
            "type": "integer",
            "minimum": 0
        },
        "videoId": {
            "description": "The ID used to identify this video within YouTube's API.",
            "type": "string",
            "pattern": "^[^ ]+$"
        },
        "embedSize": {
            "description": "The relative size the embedded YouTube player should be displayed at",
            "type": "string",
            "enum": [
                "small",
                "medium",
                "large",
                "x-large"
            ]
        }
    }
}
404 CDS Schema or Profile not found

GET All Profiles

Get a list of all current CDS profiles. More information can be found here.

GET /v1/profiles

Requires Auth?

No (open access)

Response Codes

Response Code Meaning
200 Successfully returned list of CDS profiles in JSON format 
[
    {
        "href": "/v1/profiles/aggregation"
    },
    {
        "href": "/v1/profiles/audio-card"
    },
    {
        "href": "/v1/profiles/audio"
    }
    ...
]

GET Schema

Get an individual CDS JSON Schema

GET /v1/schemas/{schemaName}

Requires Auth?

No (open access)

Response Codes

Response Code Meaning
200 Successfully returned list of CDS profiles in JSON format 
{
    "$schema": "https://json-schema.org/draft/2019-09/schema#",
    "$id": "/v1/schemas/link",
    "title": "Link",
    "description": "A link to an externally-defined location",

    "type": "object",
    "required": [
        "href"
    ],
    "properties": {
        "href": {
            "description": "An RFC3987-compliant internationalized URI",
            "type": "string",
            "format": "iri-reference"
        },
        "rels": {
            "description": "An array of RFC8288-compliant link relation types",
            "type": "array",
            "uniqueItems": true,
            "items": {
                "anyOf": [
                    {
                        "type": "string",
                        "format": "uri"
                    },
                    {
                        "type": "string",
                        "pattern": "^[a-z][a-z0-9.-]*$"
                    }
                ]
            }
        },
        "embed": {
            "description": "This attribute will be used to hold pre-fetched content from this link. If this attribute is present, it should be interpreted as the unaltered response from the link specified in the 'href' attribute.",
            "readOnly": true
        }
    }
}
400 Bad request 
{
    "meta": {
        "messages": [
            "Failed to load schema: nonExistentSchemaName.json"
        ]
    }
}
404 Schema not found

GET Client Profile

Retrieve a single client profile from CDS by name.

GET /v1/client-profiles/{profileName}

Requires Authorization Token?

No, it can be queried directly as a GET request. Example https://content.api.npr.org/v1/client-profiles/

Responses

200 - Success

On a successful retrieval, a 200 response code will be returned. The body of the response will be the JSON schema respresnting the client profile.

Example:

GET https://content.api.npr.org/v1/client-profiles/example-profile
---
200
{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "$id": "/v1/client-profiles/example-profile",
  "title": "Example Profile",

  "type": "object",
  "required": [
  ...
}

404 - Profile not found

If the requested client profile does not exist, a 404 status code will be returned with an error response.

GET https://content.api.npr.org/v1/client-profiles/invalid-profile
---
404
{
  "meta": {
    "messages": [
      "Failed to load profile invalid-profile"
    ]
  }
}

GET Query Client Profiles

Retrieve a set of client profiles from CDS

GET /v1/client-profiles

Requires Authorization Token?

No, it can be queried directly as a GET request. Example https://content.api.npr.org/v1/client-profiles/

Query Parameters

This endpoint supports two query parameters:

Name Minumum Maximum Default Description
limit 1 300 20 How many profiles to return
offset 0 (2000 - limit) 0 Where to begin the return set of profiles

limit and offset allow for a simple method of paginating through client profiles when searching for them. Together, these values cannot add up to more than 2000.

Responses

200 - Success

On a successful retrieval, a 200 response code will be returned. The body of the response will be the profiles in a JSON content view.

Example:

GET https://content.api.npr.org/v1/client-profiles?offset=0&limit=20
---
200
{
  "resources": [
    {
      "$schema": "https://json-schema.org/draft/2019-09/schema#",
      "$id": "/v1/client-profiles/example-profile",
      "title": "Example Profile",

      "type": "object",
      "required": [
      ...
    },
    ...
  ]
}

400 - Invalid request

If one or more of the query parameters given is invalid, a 400 response will be returned with an error explanation.

GET https://content.api.npr.org/v1/client-profiles?limit=all-of-them
---
400
{
  "meta": {
    "messages": [
      "all-of-them is an invalid limit value"
    ]
  }
}

© 2024 npr