Created
July 20, 2016 22:58
-
-
Save phil-lopreiato/2cdcca8f8c6688bbf40ab823c94638d5 to your computer and use it in GitHub Desktop.
Swagger Spec for TBA API v2
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "swagger": "2.0", | |
| "info": { | |
| "title": "The Blue Alliance API", | |
| "description": "Access data about the FIRST Robotics Competition", | |
| "version": "2" | |
| }, | |
| "host": "www.thebluealliance.com", | |
| "schemes": [ | |
| "http" | |
| ], | |
| "basePath": "/api/v2", | |
| "produces": [ | |
| "application/json" | |
| ], | |
| "paths": { | |
| "/teams/{page}": { | |
| "get": { | |
| "summary": "Team List Request", | |
| "description": "Returns a page containing 500 teams", | |
| "parameters": [ | |
| { | |
| "name": "page", | |
| "description": "A page of teams, zero-indexed. Each page consists of teams whose numbers start at start = 500 * page_num and end at end = start + 499, inclusive.", | |
| "in": "path", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/team_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}": { | |
| "get": { | |
| "summary": "Single Team Request", | |
| "description": "This endpoit returns information about a single team", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A single team object", | |
| "schema": { | |
| "$ref": "#/definitions/Team" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/{year}/events": { | |
| "get": { | |
| "summary": "Team Events Request", | |
| "description": "Fetch all events for a given team in a given year", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| }, | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/event_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/event/{event_key}/awards": { | |
| "get": { | |
| "summary": "Team Event Awards Request", | |
| "description": "Fetch all awards won by a single team at an event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| }, | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/award_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/event/{event_key}/matches": { | |
| "get": { | |
| "summary": "Team Event Matches Request", | |
| "description": "Fetch all matches for a single team at an event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| }, | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/match_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/years_participated": { | |
| "get": { | |
| "summary": "Team Years Participated Request", | |
| "description": "Fetch the years for which the team was registered for an event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of years where the team participated in an event", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "type": "integer" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/{year}/media": { | |
| "get": { | |
| "summary": "Team Media Request", | |
| "description": "Fetch media associated with a team in a given year", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| }, | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of Media models associated with the team in the year", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Media" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/history/events": { | |
| "get": { | |
| "summary": "Team History Events Request", | |
| "description": "Fetch all events a team has event registered for", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/event_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/history/awards": { | |
| "get": { | |
| "summary": "Team History Awards Request", | |
| "description": "Fetch all awards a team has won", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/award_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/history/robots": { | |
| "get": { | |
| "summary": "Team History Robots Request", | |
| "description": "Fetch all robots a team has made since 2015. Robot names are scraped from TIMS.", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of Robot models", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Robot" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/team/{team_key}/history/districts": { | |
| "get": { | |
| "summary": "Team History District Request", | |
| "description": "Fetch all district keys that a team has competed in", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/team_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of district keys", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/events/{year}": { | |
| "get": { | |
| "summary": "Event List Request", | |
| "description": "Fetch all events in a year", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/event_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/event/{event_key}": { | |
| "get": { | |
| "summary": "Event Info Request", | |
| "description": "Fetch details for one event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A single event model", | |
| "schema": { | |
| "$ref": "#/definitions/Event" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/events/{event_key}/teams": { | |
| "get": { | |
| "summary": "Event Teams Request", | |
| "description": "Fetch teams attending the given event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/team_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/events/{event_key}/matches": { | |
| "get": { | |
| "summary": "Event Matches Request", | |
| "description": "Fetch matches for the given event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/match_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/event/{event_key}/stats": { | |
| "get": { | |
| "summary": "Event Stats Request", | |
| "description": "Fetch stats details for one event.", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Returns a json dict with keys for 'oprs', 'dprs', and 'ccwms'.", | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/event/{event_key}/rankings": { | |
| "get": { | |
| "summary": "Event Rankings Request", | |
| "description": "Fetch ranking details for one event.", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Returns a json dict array. First row is titles, then each team in rank order.", | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/events/{event_key}/awards": { | |
| "get": { | |
| "summary": "Event Awards Request", | |
| "description": "Fetch awards for the given event", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/award_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/event/{event_key}/district_points": { | |
| "get": { | |
| "summary": "Event District Points Request", | |
| "description": "Fetch district points for one event.", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/event_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Returns a json dict containing district point data.", | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/match/{match_key}": { | |
| "get": { | |
| "summary": "Match Request", | |
| "description": "Fetch details about a single match", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/match_key_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Details about the requested match", | |
| "schema": { | |
| "$ref": "#/definitions/Match" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/districts/{year}": { | |
| "get": { | |
| "summary": "District List Request", | |
| "description": "Fetch a list of active districts in the given year", | |
| "parameters": [ | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "List of json dicts representing districts", | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/district/{district_short}/{year}/events": { | |
| "get": { | |
| "summary": "District Events Request", | |
| "description": "Fetch a list of events within a given district", | |
| "parameters": [ | |
| { | |
| "name": "district_short", | |
| "description": "Short string identifying a district (e.g. 'ne')", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/event_list_response" | |
| } | |
| } | |
| } | |
| }, | |
| "/district/{district_short}/{year}/rankings": { | |
| "get": { | |
| "summary": "District Rankings Reques", | |
| "description": "Fetch district rankings", | |
| "parameters": [ | |
| { | |
| "name": "district_short", | |
| "description": "Short string identifying a district (e.g. 'ne')", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Returns a json array of ranking data", | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/district/{district_short}/{year}/teams": { | |
| "get": { | |
| "summary": "District Teams Request", | |
| "description": "Fetch a list of teams within a given district", | |
| "parameters": [ | |
| { | |
| "name": "district_short", | |
| "description": "Short string identifying a district (e.g. 'ne')", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| { | |
| "$ref": "#/parameters/year_param" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "$ref": "#/responses/team_list_response" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "parameters": { | |
| "team_key_param": { | |
| "name": "team_key", | |
| "description": "Key identifying a single team, has format frcXXXX, where XXXX is the team number", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| "event_key_param": { | |
| "name": "event_key", | |
| "description": "Key identifying a single event, has format [year][event code]", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| "match_key_param": { | |
| "name": "match_key", | |
| "description": "Key identifying a single match, has format [event key]_[match id]", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| }, | |
| "year_param": { | |
| "name": "year", | |
| "description": "A specific year to request data for.", | |
| "in": "path", | |
| "type": "string", | |
| "required": true | |
| } | |
| }, | |
| "responses": { | |
| "event_list_response": { | |
| "description": "A list of Event objects", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Event" | |
| } | |
| } | |
| }, | |
| "team_list_response": { | |
| "description": "A list of Team objects", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Team" | |
| } | |
| } | |
| }, | |
| "match_list_response": { | |
| "description": "A list of Match objects", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Match" | |
| } | |
| } | |
| }, | |
| "award_list_response": { | |
| "description": "A list of Award objects", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Award" | |
| } | |
| } | |
| } | |
| }, | |
| "definitions": { | |
| "Team": { | |
| "type": "object", | |
| "properties": { | |
| "key": { | |
| "type": "string", | |
| "description": "TBA team key with the format frcyyyy" | |
| }, | |
| "name": { | |
| "type": "string", | |
| "description": "Official long name registerd with FIRST" | |
| }, | |
| "nickname": { | |
| "type": "string", | |
| "description": "Team nickname provided by FIRST" | |
| }, | |
| "website": { | |
| "type": "string", | |
| "description": "Official website associatd with the team" | |
| }, | |
| "locality": { | |
| "type": "string", | |
| "description": "City of team derived from parsing the address registered with FIRST" | |
| }, | |
| "region": { | |
| "type": "string", | |
| "description": "State of team derived from parsing the address registered with FIRST" | |
| }, | |
| "country_name": { | |
| "type": "string", | |
| "description": "Country of team derived from parsing the address registered with FIRST" | |
| }, | |
| "location": { | |
| "type": "string", | |
| "description": "Long form address that includes city, state, and country provided by FIRST" | |
| }, | |
| "team_number": { | |
| "type": "integer", | |
| "description": "Official team number issued by FIRST" | |
| }, | |
| "rookie_year": { | |
| "type": "integer", | |
| "description": "First year the team officially competed" | |
| }, | |
| "motto": { | |
| "type": "string", | |
| "description": "Team's motto as provided by FIRST" | |
| } | |
| } | |
| }, | |
| "Event": { | |
| "type": "object", | |
| "properties": { | |
| "key": { | |
| "type": "string", | |
| "description": "TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event." | |
| }, | |
| "name": { | |
| "type": "string", | |
| "description": "Official name of event on record either provided by FIRST or organizers of offseason event." | |
| }, | |
| "short_name": { | |
| "type": "string", | |
| "description": "Same as name but doesn't include event specifiers, such as 'Regional' or 'District'. May be null." | |
| }, | |
| "event_code": { | |
| "type": "string", | |
| "description": "Event short code, as provided by FIRST" | |
| }, | |
| "event_type_string": { | |
| "type": "string", | |
| "description": "A human readable string that defines the event type." | |
| }, | |
| "event_type": { | |
| "type": "integer", | |
| "description": "An integer that represents the event type as a constant." | |
| }, | |
| "event_district_string": { | |
| "type": "string", | |
| "description": "A human readable string that defines the event's district." | |
| }, | |
| "event_district": { | |
| "type": "integer", | |
| "description": "An integer that represents the event district as a constant." | |
| }, | |
| "year": { | |
| "type": "integer", | |
| "description": "Year the event data is for." | |
| }, | |
| "location": { | |
| "type": "string", | |
| "description": "Long form address that includes city, and state provided by FIRST" | |
| }, | |
| "venue_address": { | |
| "type": "string", | |
| "description": "Address of the event's venue, if available. Line breaks included." | |
| }, | |
| "timezone": { | |
| "type": "string", | |
| "description": "Timezone name" | |
| }, | |
| "website": { | |
| "type": "string", | |
| "description": "The event's website, if any." | |
| }, | |
| "official": { | |
| "type": "boolean", | |
| "description": "Whether this is a FIRST official event, or an offseaon event." | |
| }, | |
| "webcast": { | |
| "type": "string", | |
| "description": "If the event has webcast data associated with it, this contains JSON data of the streams" | |
| }, | |
| "alliances": { | |
| "type": "string", | |
| "description": "If we have alliance selection data for this event, this contains a JSON array of the alliances. The captain is the first team, followed by their picks, in order." | |
| } | |
| } | |
| }, | |
| "Match": { | |
| "type": "object", | |
| "properties": { | |
| "key": { | |
| "type": "string", | |
| "description": "TBA event key with the format yyyy[EVENT_CODE]_[COMP_LEVEL]m[MATCH_NUMBER], where yyyy is the year, and EVENT_CODE is the event code of the event, COMP_LEVEL is (qm, ef, qf, sf, f), and MATCH_NUMBER is the match number in the competition level. A set number may append the competition level if more than one match in required per set ." | |
| }, | |
| "comp_level": { | |
| "type": "string", | |
| "description": "The competition level the match was played at." | |
| }, | |
| "set_number": { | |
| "type": "integer", | |
| "description": "The set number in a series of matches where more than one match is required in the match series." | |
| }, | |
| "match_number": { | |
| "type": "integer", | |
| "description": "The match number of the match in the competition level." | |
| }, | |
| "alliances": { | |
| "type": "string", | |
| "description": "A list of alliances, the teams on the alliances, and their score." | |
| }, | |
| "score_breakdown": { | |
| "type": "string", | |
| "description": "Score breakdown for auto, teleop, etc. points. Varies from year to year. May be null." | |
| }, | |
| "event_key": { | |
| "type": "string", | |
| "description": "Event key of the event the match was played at." | |
| }, | |
| "videos": { | |
| "type": "string", | |
| "description": "JSON array of videos associated with this match and corresponding information" | |
| }, | |
| "time_string": { | |
| "type": "string", | |
| "description": "Time string for this match, as published on the official schedule. Of course, this may or may not be accurate, as events often run ahead or behind schedule" | |
| }, | |
| "time": { | |
| "type": "integer", | |
| "description": "UNIX timestamp of match time, as taken from the published schedule" | |
| } | |
| } | |
| }, | |
| "Award": { | |
| "type": "object", | |
| "properties": { | |
| "name": { | |
| "type": "string", | |
| "description": "The name of the award as provided by FIRST. May vary for the same award type." | |
| }, | |
| "award_type": { | |
| "type": "integer", | |
| "description": "An integer that represents the award type as a constant." | |
| }, | |
| "event_key": { | |
| "type": "string", | |
| "description": "The event_key of the event the award was won at." | |
| }, | |
| "recipient_list": { | |
| "type": "string", | |
| "description": "A list of recipients of the award at the event. Either team_number or awardee for individual awards." | |
| }, | |
| "year": { | |
| "type": "integer", | |
| "description": "The year this award was won." | |
| } | |
| } | |
| }, | |
| "Media": { | |
| "type": "object", | |
| "properties": { | |
| "type": { | |
| "type": "string", | |
| "description": "The string type of the media element" | |
| }, | |
| "foreign_key": { | |
| "type": "string", | |
| "description": "The key used to indentify this media element on the remote site (e.g YouTube video key)" | |
| }, | |
| "details": { | |
| "type": "string", | |
| "description": "If the media requires it, a json dict of additional information" | |
| } | |
| } | |
| }, | |
| "Robot": { | |
| "type": "object", | |
| "properties": { | |
| "key": { | |
| "type": "string", | |
| "description": "A key identifying the robot object. Formed like [team_key]_[year]" | |
| }, | |
| "team_key": { | |
| "type": "string", | |
| "description": "The associated Team key" | |
| }, | |
| "year": { | |
| "type": "integer", | |
| "description": "The year this Robot model referes to" | |
| }, | |
| "name": { | |
| "type": "string", | |
| "description": "The robot name in this year" | |
| } | |
| } | |
| } | |
| } | |
| } | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment