Using Shield

Shield is HTTP-based and aims to keep those familiar with HTTP semantics comfortable using Shield. Features listed here are available across all of Shield's endpoints. You can use Shield to query data, post videos, get NFL stats and a variety of other tasks that you might be interested in doing.

Accessing the API

The Shield API is accessed at <domain>. A sample unauthenticated request might look like:

GET https://<domain>/v1/games
HEADER : Authorization: Bearer {TOKEN}

To retrieve the all games sorted by the default sort order.

Most Shield API requests will require the use of access tokens which your app can generate by using Shield's Identity system.

API requests must use HTTPS, HTTP requests will result in 400 Bad Request responses.

Identity

Most Shield API requests will require authorization credentials to be able to use it. Shield relies on the industry standard OAuth 2.0 protocol for granting access. Your application must send an OAuth 2.0 token with any request that accesses private user data. Your application sends a client ID and, possibly, a client secret to obtain a token.

Get auth credentials

API Requests

Shield uses standard HTTP calls. Any web programming language (PHP, Ruby, Perl, Python, Java, Objective C, C#...) should be able to make and receive HTTP calls.

URLs

Each of our endpoints represent a resource, or collection of resources and is identified by a unique URL, such as:

https://<domain>/v1/games/<game_id>

The prefix v1 is the version specifier and must be present. When significant changes are made to the API (changes that would break compatibility with existing applications) this value will change. URL paths may contain the unique identifiers for resources. These are identified by angle brackets as in above. Before calling Shield, a valid identifier must be substituted for these placeholders. Identifier (ID) parameters must appear in the URL and cannot be used as GET parameters. All ID parameters listed in the URL pattern must be present.

API requests must use HTTPS, HTTP requests will result in 400 Bad Request responses.

HTTP Methods

Use standard HTTP methods to take actions against a resource:

Content-type

Shield API exposes data in JSON. All requests MUST specify valid JSON content-type:

content-type: application/json

Encoding

Shield API returns UTF-8 encoded JSON. Although not mandatory, it is safer to specify UTF-8 encoding acceptance.

content-type: application/json; charset=UTF-8

Resource Object Representation

Every object is represented in its expanded form. To illustrate, see this following example where the venue property contains all of it's default properties opposed to offering a pointer to the venue.

Example: A team object below represented in the API, default fields are shown.

{
    id: "48134bf5-b4e1-4955-9c58-632bc1b99ca6",
    season: 2014,
    fullName: "Denver Broncos",
    nickName: "Broncos",
    abbreviation: "DEN",
    conference: "AFC",
    division: "ACS",
    venue: {
        "id" : "...",
        "name" : "...",
        "location" : "...",
        "type" : "...",
        ...
    }
}

*Shield API does not support resource object representation as ID or resource URL inside any response.

Unique Identifiers (IDs)

Each resource object contains a unique identifier, or ID, when available. An ID is represented by an "id" key. Unless specifically stated, all unique identifiers generated by the API are UUIDs version 4. The API also supports client generated valid UUIDs.

Note: UUIDs are strings that only contain alphanumeric characters, dashes and underscores.

API Responses

Shield values consistency. API responses will return the response objects requested unless something doesn't quite work out.

See Error Response for what you can expect when you encounter an error.

API Response Format

Currently, Shield returns the HTTP response body formatted in JSON.

Date Format

All Date/Time fields will be ISO 8601 compliant and in UTC.

Example:

2014-08-20T18:00:00.000Z

Error Handling

Due to the nature of remote APIs, services can be temporarily unavailable due to reasons outside of your or the NFL's control. You should assume that any call you make to Shield includes error-handling logic. This can include any request such as:

See Error Response for what response body you can work with.

and Global Error Codes

Features

There are three powerful features of the API we will introduce here.

Field Selection

Field selection allows you to "shape" your response to your specific needs.

The fs parameter is an optional parameter for any API request that retrieves a resource. The parameter's value identifies the all the properties in the called endpoint's object graph that should be included in an API response.
As such, the fs parameter allows you to select the parts of resources that your application actually uses. This feature serves several purposes:

GET /articles/daef6ef9-55d9-455c-9086-fa029187ed3c?fs={id,type,title,caption,thumbnail{id},createdDate,author{lastName,emailAddress},body}

Querying

Shield provides a powerful querying capability. Not only can you query root level endpoints, in some cases, Shield supports subqueries. The query syntax is similar to mongo query syntax and allows for conditional and logical AND/OR operators how ever nested and combined.

All root endpoints can be queried, sorted and paginated using a query parameter s. We've provided lots of examples and a guide to help demonstrate the power of this feature.

GET /games?s={"$query" : {"season": "2014", "seasonType": "REG", "week": 1}, "$sort" : {"gameTime" : 1}}&fs={id, season, seasonType, gameTime, homeTeam, visitorTeam}

Pagination

All collections represented via the API are paginated--nested collections within parent resources or otherwise. Each collection is wrapped with a Pager.

Example:

{
    pager: {...},
    data: [...]
}

Pagination is controlled using keywords like $take and $skip in the query syntax sent via the querying parameter, s. For more information including examples, see the detailed pagination reference, see Pager.

Sorting

Sorting is supported using the $sort keyword in the data structure sent via the querying parameter (s). The value of $sort consists of the name of field to sort and the sort direction. The possible values for Sort direction are (1/-1) what means (descending/ascending)

Example:

s={"$sort:{"firstName":1}"}).

All of our endpoints are have a default sort order to ensure consistent pagination behavior.

By default, if no specific sorting has been included in the request, the items returned in a list will be sorted based in the natural order defined in the respective object type.

Example: Default Sorting for Person
Index Field Sort Order
1 lastName ASC
2 firstName ASC
3 birthDate DESC