Partial Response
This page will help you understand how Sport API handles partial response
When building any networked application we understand how important it is to keep the data transferred over the network to an absolute minimum. This is especially important when building mobile and web applications where increased network overhead can seriously impact user experience (and also bandwidth usage bills!).
Recognising this, the Sport API fully supports partial response when using the JSON media type, meaning that you can determine the exact fields you'd like returned in your API responses.
In order to return a partial representation of a response use the fields query parameter. Let's take a look at an example of how partial response could be used using this parameter.
To demonstrate how this can be used let's make the following request to return the 2 latest items:
curl \
-H "Accept: application/json" \
-H "apikey: <API KEY>" \
https://sport.api.press.net/v1/stage?sport=3&start=2017-01-01&limit=1
Upon execution, the Sport API returns a "full-fat" response:
{
"offset": 0,
"limit": 1,
"hasNext": true,
"hasPrevious": false,
"items": [
{
"id": 845642,
"name": "Tournament of Champions",
"gender": "male",
"start": "2017-01-05",
"end": "2017-01-08",
"country": {
"id": 16,
"name": "USA"
},
"season": {
"id": 10683,
"name": "2017"
},
"tournament": {
"id": 431,
"name": "PGA Tour",
"gender": "male"
},
"sport": {
"id": 3,
"name": "Golf"
},
"updated": "2017-01-04T05:23:22Z",
"meta": {
"currency": {
"code": "stage:currency",
"name": "Currency",
"value": "US Dollar"
},
"length": {
"code": "stage:length",
"name": "Length",
"value": "6816"
},
"par": {
"code": "stage:par",
"name": "Par",
"value": "73"
},
"prize": {
"code": "stage:prize",
"name": "Prize",
"value": "6000000"
},
"rounds": {
"code": "stage:rounds",
"name": "Rounds",
"value": "4"
},
"tee-time-round-1": {
"code": "stage:tee-time-round-1",
"name": "Tee Time Round 1",
"value": "2017-01-05T20:20:00Z"
},
"tee-time-round-2": {
"code": "stage:tee-time-round-2",
"name": "Tee Time Round 2",
"value": "2017-01-06T20:20:00Z"
},
"tee-time-round-3": {
"code": "stage:tee-time-round-3",
"name": "Tee Time Round 3",
"value": "2017-01-07T18:35:00Z"
},
"tee-time-round-4": {
"code": "stage:tee-time-round-4",
"name": "Tee Time Round 4",
"value": "2017-01-08T17:35:00Z"
},
"type": {
"code": "stage:type",
"name": "Type",
"value": "Stroke Play"
},
"venue": {
"code": "stage:venue",
"name": "Venue",
"value": "The Plantation Course at Kapalua"
}
},
"updated": "2017-01-04T05:23:22Z",
"venues": [
{
"id": 4230,
"name": "The Plantation Course at Kapalua",
"type": "Golf course",
"country": {
"id": 16,
"name": "USA"
},
"meta": {
"city": {
"code": "venue:city",
"name": "City",
"value": "Maui"
},
"latitude": {
"code": "venue:latitude",
"name": "Latitude",
"value": "21.00718"
},
"longitude": {
"code": "venue:longitude",
"name": "Longitude",
"value": "-156.64106"
},
"length1": {
"code": "venue:length1",
"name": "Length1",
"value": "476"
},
"length2": {
"code": "venue:length2",
"name": "Length2",
"value": "199"
},
"length3": {
"code": "venue:length3",
"name": "Length3",
"value": "348"
},
"length4": {
"code": "venue:length4",
"name": "Length4",
"value": "349"
},
"length5": {
"code": "venue:length5",
"name": "Length5",
"value": "487"
},
"length6": {
"code": "venue:length6",
"name": "Length6",
"value": "364"
},
"length7": {
"code": "venue:length7",
"name": "Length7",
"value": "472"
},
"length8": {
"code": "venue:length8",
"name": "Length8",
"value": "186"
},
"length9": {
"code": "venue:length9",
"name": "Length9",
"value": "476"
},
"length10": {
"code": "venue:length10",
"name": "Length10",
"value": "324"
},
"length11": {
"code": "venue:length11",
"name": "Length11",
"value": "150"
},
"length12": {
"code": "venue:length12",
"name": "Length12",
"value": "384"
},
"length13": {
"code": "venue:length13",
"name": "Length13",
"value": "372"
},
"length14": {
"code": "venue:length14",
"name": "Length14",
"value": "279"
},
"length15": {
"code": "venue:length15",
"name": "Length15",
"value": "508"
},
"length16": {
"code": "venue:length16",
"name": "Length16",
"value": "334"
},
"length17": {
"code": "venue:length17",
"name": "Length17",
"value": "502"
},
"length18": {
"code": "venue:length18",
"name": "Length18",
"value": "606"
},
"par1": {
"code": "venue:par1",
"name": "Par1",
"value": "4"
},
"par2": {
"code": "venue:par2",
"name": "Par2",
"value": "3"
},
"par3": {
"code": "venue:par3",
"name": "Par3",
"value": "4"
},
"par4": {
"code": "venue:par4",
"name": "Par4",
"value": "4"
},
"par5": {
"code": "venue:par5",
"name": "Par5",
"value": "5"
},
"par6": {
"code": "venue:par6",
"name": "Par6",
"value": "4"
},
"par7": {
"code": "venue:par7",
"name": "Par7",
"value": "4"
},
"par8": {
"code": "venue:par8",
"name": "Par8",
"value": "3"
},
"par9": {
"code": "venue:par9",
"name": "Par9",
"value": "5"
},
"par10": {
"code": "venue:par10",
"name": "Par10",
"value": "4"
},
"par11": {
"code": "venue:par11",
"name": "Par11",
"value": "3"
},
"par12": {
"code": "venue:par12",
"name": "Par12",
"value": "4"
},
"par13": {
"code": "venue:par13",
"name": "Par13",
"value": "4"
},
"par14": {
"code": "venue:par14",
"name": "Par14",
"value": "4"
},
"par15": {
"code": "venue:par15",
"name": "Par15",
"value": "5"
},
"par16": {
"code": "venue:par16",
"name": "Par16",
"value": "4"
},
"par17": {
"code": "venue:par17",
"name": "Par17",
"value": "4"
},
"par18": {
"code": "venue:par18",
"name": "Par18",
"value": "5"
}
}
}
],
"links": [
{
"rel": "self",
"href": "http://sport-uat.api.press.net/v1/stage/845642"
}
]
}
]
}
Whilst this response is great if you require all of the metadata contained within the document, it's not great if your application only requires a certain selection of fields (say id, name and prize) or if your users are constrained by their network.
With this in mind, you can utilise the Sport API's partial response feature to trim the response payload down to your exact requirements.
Let's try the same request but this time only selecting the JSON fields we're interested in:
curl \
-H "Accept: application/json" \
-H "apikey: <API KEY>" \
https://sport.api.press.net/v1/stage?sport=3&start=2017-01-01&limit=1&fields=items(id,name,meta(prize))
When executing this request, we are now returned only the fields we're interested in, meaning a considerably smaller payload for a client application to process. The subsequent response:
{
"items": [
{
"id": 845642,
"name": "Tournament of Champions",
"meta": {
"prize": {
"code": "stage:prize",
"name": "Prize",
"value": "6000000"
}
}
}
]
}
The format of the fields request parameter value is loosely based on XPath syntax. Additional examples are provided in the following section:
- Use a comma-separated list to select multiple fields (e.g. total,limit,offset).
- Use a/b to select a field b that is nested within field a; use a/b/c to select a field c nested within b. For example:?fields=prize/value.
- Specify field sub-selectors to request only specific sub-fields by placing expressions in parentheses "( )" after any selected field. For example: ?fields=items(id) returns only the item id.
- Use wildcards in field selections, if needed. For example: ?fields=meta/* selects all items in the meta object.
Updated almost 7 years ago