Field Selectors

Field Selector is a query parameter that can be passed to any GET request endpoint that denote which fields should be populated in the response. Note that this is a hybrid approach of many other ideas such as GraphQL, LinkedIn Field Selector.

Default Fields

All object in the Shield API have a notion of default fields. Only these fields are returned when no field selectors are passed in.

Syntax

Field selectors can be passed with query parameter fs. Field selection is done by specifying a list of field names. Users can select fields on root object as well as embedded objects or embedded collection elements.

Example

Field Selector:

{
    id, 
    season, 
    seasonType, 
    week, 
    visitorTeam {
        abbreviation
    }, 
    homeTeam {
        abbreviation
    }
}

Here, season field of game (root domain object) will be returned as well as abbreviation field of visitorTeam embedded object.

Request:

/games/862bc634-5daf-4c07-b557-a88d03d973ec?fs={id, season, seasonType, week, visitorTeam{abbreviation}, homeTeam{abbreviation}}

Response:

{
    "id": "862bc634-5daf-4c07-b557-a88d03d973ec",
    "season": 2014,
    "seasonType": "REG",
    "week": 1,
    "visitorTeam": {
        "abbreviation": "DEN"
    },
    "homeTeam": {
        "abbreviation": "IND"
    }
}

Overriding Default

When field selectors are used, only fields that are in the field selection will be in the response regardless of the field being default field or not. Note that if a selected field is an embedded object, then the default values of that object will be returned unless it is they are explicitly overridden in the field selector.

Example

Field Selector:

{
    id, 
    season, 
    seasonType, 
    week, 
    visitorTeam {
        abbreviation
    }, 
    homeTeam
}

Here, homeTeam object will have default fields but visitorTeam will only have abbreviation field because we overrode defaults.

Request:

/games/862bc634-5daf-4c07-b557-a88d03d973ec?fs={id, season, seasonType, week, gameStatus, visitorTeam{abbreviation}, homeTeam

Response:

{
    "id": "862bc634-5daf-4c07-b557-a88d03d973ec",
    "season": 2014,
    "seasonType": "REG",
    "week": 1,
    "visitorTeam": {
        "abbreviation": "DEN"
    },
    "homeTeam" : {
        "id" : "3085723e-5daf-4c07-b557-a88d03d973ec",
        "name":"Colts",
        "fullName": "Indianapolis Colts",
        "nickName": "Colts",
        "abbreviation": "IND"
    }
}