Muskego Hitmen API Services

It's for your own good...really

Overview

With the Hitlist Media API, you can retrieve historical data, and content created by our staff and users. To get started, you must create an account and request an API Key. Your API key must be sent with every API request. To request an API key send an email to webmaster -[at]- muskegohitmen dot com.

Definitions

Below is a list of terms and definitions used in this document

  • Resource - A mapping between an URL path and a data type. The resource defines a list of fields that will be returned within the response. There are primarily two types of resources
    • List Resource - Returns zero or more records. List resource can be filtered and sorted to customize the result set. A List Resource typically retuns fewer fields than the corresponding Detail Resource for the same item. However, each record will contain a field named "resource_uri" providing a link to the Detail Resource for that item.
    • Detail Resource - Returns all information about a single item. A Detail Resource contains information about the requested object as well as all of its relations to other objects.
  • API Key - An alpha-numberic string used to identify the user making the request
  • Filter - A parameter passed with the request that filters the result set based on the filter value. Most commonly used on List Resources

Making Requests

Data access is provided in a RESTful style to make data access as easy as possible. You can access Our data with anything that can make a web request.

Each request is made against a specific resource. A resource defines the type of object that will be returns, the fields on that object and any filters that can be used.

List Resource Request

A request to a List Resource contains resource name, type, api key, username and a data format. A request may optionally contain filters. To retrive all of the rosters a request would look like this:

"http://www.muskegohitmen.com/team/rosters/?username=myusername&api_key=ad492nd9gSDK498240sdkeo338185&formt=json"
										

Detail Resource Request

A request to a Detail Resouce contains a resource name, type, the ID of the object being queried, an API KEy, username, and a data format. A request for a specific play from the Muskego Hitmen would look like this:

"http://www.muskegohitmen.com/team/players/152/?username=myusername&api_key=ad492nd9gSDK498240sdkeo338185&formt=json"
										

The URL is easier to understand when broken appart. The "/team/" path refers to the application on the muskego hitmen webiste to pull data from. The "/players/" path referes to the players data resource, and the "152" is the ID number of the player to lookup. The query string ( everything after "?" ) holds the rest of the request. The username is username of a user account on the Muskego Hitmen Website. The api_key is the api key associated with the user account. The format determines what format data will be returned in. So this URL will return a Detail Resource for Player 152.

Pagination

For performance resons result sets are limited to a low number. However, you have the ability to make subsequent request for more data. A special offset filter is available on all List Resources. By specifing an offset, the client can start retrieving results min-way through the result set. For example, if there are 400 players matching a request, the following for requests would retrieve all of the players :

"http://www.muskegohitmen.com/team/players/?username=myusername&api_key=ad492nd9gSDK49824&formt=json"
"http://www.muskegohitmen.com/team/players/?username=myusername&api_key=ad492nd9gSDK49824&formt=json&offset=100"
"http://www.muskegohitmen.com/team/players/?username=myusername&api_key=ad492nd9gSDK49824&formt=json&offset=200"
"http://www.muskegohitmen.com/team/players/?username=myusername&api_key=ad492nd9gSDK49824&formt=json&offset=300"
										

Handling Responses

Every response contains a set of meta data. Using this meta data you can determine the size of the entire dataset, and infer pagination results. Responses will also contain property called "objects" which will contain a list of all the returned objects

Meta attributes
limitThe current limit on the result set
nextThe url for the next page of the data set or null
previousThe url for the next page of the data set of null
offsetThe current offset in the dataset


Delivery Formats

We currently support: XML,JSON, and YAML. When making a request you must specify the response format you prefer with the "format" option. For example, if you want your response to be returned in JSON, you would pass "format=json".

XML - XML stands for Extensible Markup Language. XML parsers can be founc in nearly every programming language. Here is an example XML Response:


	
		/api/team/players/?username=myusername&api_key=5ndje5482nh4vfc&format=xml&limi=20 
		186
		
		20
		0
	
	
		
			 
			67
			Abraham
			Cedarberg HS
			2004
			All-Star

			Brad
			1
			UW-Platville

			KP
			6
			Brad Abraham
			6.0
			Kicker / Punter
			0
			http://media.muskegohitmen.com/images/sitewide/The-H-Text_blk_jpg_70x70_q85.jpg
			6.5
			/api/team/players/67/
		
	

									 

JSON - JSON stands for Javascript Object Notation. JSON can be parsed natively by javascript. Many other languages have libraries that convert native structures to and from JSON. JSON is generally smaller than XML, which is convenient for smaller and faster request. Here is an example of a json response

{
	"meta": {
		"limit": 20,
		"next": "/api/team/players/?username=myusername&api_key=5ndje5482nh4vfc&format=json&limit=20",
		"offset": 0,
		"previous": null,
		"total_count": 186
	},
	"objects": [
		{
			"height_inches": 1,
			"hs_attended": "Cedarberg HS",
			"id": "67",
			"lname": "Abraham",
			"name": "Brad Abraham",
			"number": 9,
			"occupation": "",
			"points": 0,
			"position": "KP",
			"position_description": "Kicker / Punter",
			"rank": "allstar",
			"rank_description": "All-Star",
			"rating": null,
			"resource_uri": "/api/team/players/67/",
			"shuttle_time": 6.5,
			"standing": 2,
			"weight": 225,
			"years_exp": 1
		}
	]
}
									 

YAML - YAML stands for YAML Ain't Markup Language. YAML is a capable human-readable data format. Although not widely used across the web, The Muskego Hitmen API support YAML Serialization. Visit the YAML Website for more information.


Filtering Data

Basic Filtering

Becuase some List Resources can provide a rather large result set, most List Resources provide a simple way to filter results down to only return the data you really want. You can add a filter as a part of the query string on each request. Filters take the format of <FIELD_NAME>=<VALUE>. For example, If you wanted to find all of the teams from the IFL in the city of milwaukee, you would use the following URL to filter the team List Resource

"/api/league/teams/?team_city=milwaukee"

Advanced Filtering

You have seen basic filters earlier with limit, format and offset. More advanced filters can be applied with a "Double Underscore" syntax which is applied to the field name you wish to filter on - <FIELD_NAME>__<FILTER_TYPE>=<VALUE>. For example, if you wanted to find all of the teams in the IFL whose name started with the letter `M`, you would make a request like this:

"/api/league/teams/?team_name__startswith=M"

For certain fields, the Double Underscore syntax can be used to look up fields within nested reseources before applying a filter - <FIELD_NAME>__<NESTED_FIELD_NAME>__<FILTER_TYPE>=<VALUE>. For Example, if you wanted to find all of the games for a specific team during a specific season, you could make a request like this:

"/api/league/teams/?home_team__team_name=Hitmen&season__season_year__year=2010"

Filter Types
exact filters for an exact value
iexact filters for an exact value with a case insensitive match
contains Returns results where the value is contained in the fields value. eg "Milwaukee" contains "wauke"
in Allows you to specify a list of values to look up. eg __in=1,2,3,4
gt Greater Than - looks for field values greater than the specified value. Only valid for number fields
gte Greater Than Equal - looks for field values greater than or equal to the specified values. only valid for number fields
lt Less Than - looks for field values less than the specified value. Only valid for number fields
lte Less Than Equal - looks for field values less than or equal to the specified values. only valid for number fields
startswith Looks for field values that start with the specified value
istartswith Looks for field values that start with the specified value on a case insensitive match
endswith Looks for field values that end with the specified value
iendswith Looks for field values that end with the specified value on a case insensitive match
year Looks for field values that are within the specified year. Only valid on date or date time fields.

Resources

League Resources

League Resources are data resource pertaining to the IFL as a whole and not specifically to the Muskego Hitmen. Leagure resources are made up of Teams, Games, Conferences, and Seasons.
Teams
Resource: /api/league/teams/

Field Filters
Field Name Filters
team_name exact, iexact, startswith, istartswith
is_active exact
team_city exact, iexact, startswith, istartswith
id in, exact

Games
Resource: /api/league/games/

Field Filters
Field Name Filters
season All filters & relations supported
home_team All filters & relations supported
away_team All filters & relations supported

Seasons
Resource: /api/league/season/

Field Filters
Field Name Filters
season_year No Filtering Available

Conference
Resource: /api/league/conference/

Field Filters
Field Name Filters
conference_name No Filtering Available