2. RESTful API Models and Design - adle29/cs373-idb GitHub Wiki

Data Models AND RESTful API Design

Data Models

We have 5 data models which structure our API.

Model Diagram

###Season

  • season_id
    • An unique id for a league season
  • season_name
    • A string which represents the name of the season
  • league
    • A small string which is a code that represents a leagues
  • year
    • An integer that represents the year in which the season takes place
  • num_teams
    • An integer that represents the number of teams participating in the season
  • num_games
    • An integer that represents the number of games played in the season
  • num_match_days
    • An integer that represents the number of match days in the season
  • curr_match_day
    • An integer that represents the most current match day in the season

####Relationships A season has a one-to-many relationship with games as there are multiple games in a season. Season also has a one-to-many relationship with Standing, as each team has a standing in a Season. Seasons also have a many-to-many relationship with teams, as multiple teams play in a season but teams also play in multiple seasons.

###Game

  • game_id
    • An unique id for the specific game
  • date
    • A string which represents the date of the game
  • time
    • A string which represents the time of the game
  • home_team
    • A string corresponding to name of the home team competing in the game
  • away_team
    • A string corresponding to the name of the away team competing in the game
  • home_team_score
    • An integer representing the score of the Home team
  • away_team_score
    • An integer representing the score of the Away team
  • match_day
    • An integer representing the match day the game fell on

####Relationships A Game has a many-to-one relationship with Season, as there are many games in a season. Games also have a many-to-many relationship with Teams as teams play many games and a game is a contest between two teams.

###Team

  • team_id
    • An unique id for a specific team
  • team_name
    • A string representing the name of the team
  • logo_url
    • A string representing a url of the team's logo
  • nickname
    • A string corresponding to the nickname of the team, if it has one
  • market_val
    • A string corresponding to the current market value of the team
      • A string is used to allow for Unicode characters for different currency types

####Relationships A Team has a many-to-many relationship with Seasons as multiple teams compete in season and teams compute in multiple seasons. Teams also have a many-to-many relationship with Game as teams play multiple games and a Game is a contest between two teams. Teams also have a one-to-many relationship with players as a team is a collection of players. Teams also have a one-to-many relationships with Standings as teams can have multiple standings in different seasons but a standing is the rank and evaluation for one team in a season.

###Standing

  • standing_id
    • An integer corresponding unique id for a specific standing
  • match_day
    • An integer representing the match day used to give context to the standing
  • group
    • A string representing the cohort of teams that play together in a season of which the team is a member
  • rank
    • An integer corresponding to the rank of the team in question
  • matches_played
    • An integer corresponding to the number of matches played by the team
  • points
    • An integer representing the number of points accumulated by the team in question
  • goals_for
    • An integer representing the number of goals scored by the team in question
  • goals_against
    • An integer representing the number of goals allowed by the team's goaltender

####Relationships Standing has two relationships. It has a many-to-one relationship with teams as a team has multiple standings corresponding with the multiple seasons in which they compete in. It also has a many to one relationship with Seasons, as for a given season, there are many standings corresponding to all the teams in the contest.

###Player

  • player_id
    • An integer representing unique id for a specific player
  • name
    • A string value representing the name of the player
  • position
    • A string corresponding to the position of the player
  • nation
    • A string corresponding to the nationality of the player
  • birth
    • A string representing the player's birthday
  • jersey_num
    • An integer value representing the jersey number the player holds

####Relationships

Player only has one relationship. It has a many-to-one relationship with Team as there are multiple players in a team.

RESTful API

For our API, we wanted to keep cleanliness and functionality in mind. We made the data sparse enough as to allow for anyone to grab the data they want, reducing the number of calls. Yet, we organized our relationships in a manner as to allow for multiple calls to our API to result in the possibility in retrieving non-trivial collections of data.

As of the current moment, we designed our API to only allow developers to GET data and not POST any data. In the future, we aspire to use other soccer APIs to update our database in a timely and redundant manner.

You can see our API at Apiary

####RESTful API Calls

The data on the site is organized in JSON. We decided to use JSON because it is the industry standard in data formats right now (especially in the domain of web development).

To retrieve a list of all soccer seasons: [GET] goalazostats.me/seasons

  • The call to the endpoint above will return data congruent to the following code:
{
   "totalNumberOfSeasons":13,
   "seasons":[
      {
         "season_id":1,
         "season_name":"1. Bundesliga 2015/16",
         "league":"BL1",
         "year":2015,
         "num_teams":18,
         "num_games":306,
         "num_match_days":34,
         "cur_match_day":34
      },
      {
         "season_id":2,
         "season_name":"2. Bundesliga 2015/16",
         "league":"BL2",
         "year":2015,
         "num_teams":18,
         "num_games":306,
         "num_match_days":34,
         "cur_match_day":34
      },
      
      ...
      
      {
         "season_id":10,
         "season_name":"3. Bundesliga 2015/16",
         "league":"BL3",
         "year":2015,
         "num_teams":20,
         "num_games":380,
         "num_match_days":38,
         "cur_match_day":38
      }
   ]
}

  • [GET] goalazostats.me/seasons/<offset>

    • The endpoint can be given an offset as a parameter. The default offset is 0. When one makes a requests with a specified offset, it retrieves 10 seasons from the offset onward.
    • A call to goalazostats.me/seasons/5 returns output congruent to the following:
    {
 "totalNumberOfSeasons":13,
 "seasons":[
    {
       "season_id":6,
       "season_name":"Primera Division 2015/16",
       "league":"PD",
       "year":2015,
       "num_teams":20,
       "num_games":380,
       "num_match_days":38,
       "cur_match_day":38
    },
     ...
    {
       "season_id":13,
       "season_name":"League One 2015/16",
       "league":"EL1",
       "year":2015,
       "num_teams":24,
       "num_games":552,
       "num_match_days":46,
       "cur_match_day":16
    }
 ]

}


To retrieve a single soccer season:
  `[GET] goalazostats.me/season/<season_id>`
- A call to `goalazostats.me/season/5` will return data congruent to the following:

{ "season_id":5, "season_name":"Premier League 2015/16", "league":"PL", "year":2015, "num_teams":20, "num_games":380, "num_match_days":38, "cur_match_day":38 }


To retrieve a list of soccer team in a season:
    `[GET] goalazostats.me/season/<season_id>/teams`

To retrieve a list of soccer standings for a season:
    `[GET] goalazostats.me/season/<season_id>/standings`
    - A call to to `goalazostats.me/season/1/standings` will return data congruent to the following:

{ "season":{ "season_id":1, "season_name":"1. Bundesliga 2015/16", "league":"BL1", "year":2015, "num_teams":18, "num_games":306, "num_match_days":34, "cur_match_day":34 }, "standings":[ { "match_day":34, "group":"A", "rank":1, "matches_played":34, "points":88, "goals_for":80, "goals_against":17, "team_id":1, "logo_url":"http://upload.wikimedia.org/wikipedia/commons/c/c5/Logo_FC_Bayern_M%C3%BCnchen.svg", "team_name":"FC Bayern M\u00fcnchen" }, ... { "match_day":34, "group":"A", "rank":18, "matches_played":34, "points":25, "goals_for":31, "goals_against":62, "team_id":8, "logo_url":"http://upload.wikimedia.org/wikipedia/de/c/cd/Hannover_96_Logo.svg", "team_name":"Hannover 96" } ] }


To retrieve a list of soccer teams:
   `[GET] goalazostats.me/teams`
- The endpoint can be given an offset as a parameter. The default offset is 0. When one makes a requests with a specified offset, it retrieves 10 teams from the offset onward. 
- A request to `[GET] goalazostats.me/teams/5` will return data congruent to the following:

{ "totalNumberOfTeams":18, "teams":[ { "api_team_id":1, "team_id":18, "team_name":"1. Fc K\u00f6ln", "logo_url":"http://upload.wikimedia.org/wikipedia/de/1/16/1._FC_K%C3%B6ln.svg", "nickname":"K\u00f6ln", "market_val":"57,800,000 \u20ac", "players":[ 1, ... 21, 22 ] }, ... { "api_team_id":6, "team_id":12, "team_name":"Fc Schalke 04", "logo_url":"http://upload.wikimedia.org/wikipedia/de/6/6d/FC_Schalke_04_Logo.svg", "nickname":"Schalke", "market_val":"213,875,000 \u20ac", "players":[ 126, ... 155 ] } ] }


To retrieve a single soccer team:
    `goalazostats.me/team/<team_id>`
 
- A call to `goalazostats.me/team/1` will return data congruent to the following:

{ "api_team_id":5, "team_id":1, "team_name":"Fc Bayern M\u00fcnchen", "logo_url":"http://upload.wikimedia.org/wikipedia/commons/c/c5/Logo_FC_Bayern_M%C3%BCnchen.svg", "nickname":"Bayern", "market_val":"617,100,000 \u20ac", "players":[ 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114,call to the request above will return data congruent to the following 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125 ] }


- `goalazostats.me/team/<team_id>/players`
	- This endpoint can also access the players in the team:
	- A call to `goalazostats.me/team/1/players` will return data congruent to the following:

[ { "player_id":101, "name":"Manuel Neuer", "nation":"Germany", "birth":"1986-03-27", "position":"Keeper", "jersey_num":1 }, { "player_id":102, "name":"Sven Ulreich", "nation":"Germany", "birth":"1988-08-03", "position":"Keeper", "jersey_num":26 }, ... { "player_id":125, "name":"Serdar Tasci", "nation":"Germany", "birth":"1987-04-24", "position":"Centre Back", "jersey_num":4 } ]


- `goalazostats.me/team/<team_id>/games`
	- A call to `goalazostats.me/team/1/games` will return data congruent to the following:

[ { "game_id":11, "date":"2015-08-22T13:30:00Z", "away_team_score":2, "home_team_score":1, "home_team_id":6, "away_team_id":1, "match_day":2, "home_team_name":"Tsg 1899 Hoffenheim", "away_team_name":"Fc Bayern M\u00fcnchen" }, { "game_id":40, "date":"2015-09-19T13:30:00Z", "away_team_score":3, "home_team_score":0, "home_team_id":7, "away_team_id":1, "match_day":5, "home_team_name":"Sv Darmstadt 98", "away_team_name":"Fc Bayern M\u00fcnchen" }, ... { "game_id":292, "date":"2016-05-07T13:30:00Z", "away_team_score":2, "home_team_score":1, "home_team_id":10, "away_team_id":1, "match_day":33, "home_team_name":"Fc Ingolstadt 04", "away_team_name":"Fc Bayern M\u00fcnchen" } ]





To retrieve a list of all recent soccer players:
`[GET] goalazostats.me/players`
- `[GET] goalazostats.me/players/<offset>`
- The endpoint can be given an offset as a parameter. The default offset is 0. When one makes a requests with a specified offset, it retrieves 10 players from the offset onward. 
- A call to `goalazostats.me/players/5` returns output congruent to the following:

{ "players":[ { "player_id":364, "name":"Albian Ajeti", "nation":"Switzerland", "birth":"1997-02-26", "position":"Centre Forward", "jersey_num":17 }, ... { "player_id":213, "name":"Alexander Milosevic", "nation":"Sweden", "birth":"1992-01-30", "position":"Centre Back", "jersey_num":24 } ], "totalNumberOfPlayers":508 }


To retrieve a list of soccer games:
- `[GET] goalazostats.me/games`
- `[GET] goalazostats.me/games/<offset>`
  - The endpoint can be given an offset as a parameter. The default offset is 0. When one makes a requests with a specified offset, it retrieves 10 games from the offset onward. 
- A call to `goalazostats.me/games/5` returns output congruent to the following:

{ "totalNumberOfGames":306, "games":[ { "game_id":2, "date":"2015-08-15T13:30:00Z", "away_team_score":1, "home_team_score":0, "home_team_id":3, "away_team_id":4, "match_day":1, "home_team_name":"Fc Augsburg", "away_team_name":"Hertha Bsc" }, ... { "game_id":12, "date":"2015-08-22T13:30:00Z", "away_team_score":1, "home_team_score":1, "home_team_id":18, "away_team_id":15, "match_day":2, "home_team_name":"1. Fc K\u00f6ln", "away_team_name":"Vfl Wolfsburg" } ] }

⚠️ **GitHub.com Fallback** ⚠️