apiary.apib

FORMAT: 1A
HOST: http://theaustinites.pythonanywhere.com/

# Austin City Limits Project API
ACL Project is a representation of the sponsors, stages, and artists appearing at 
**Austin City Limits**.

The API allows **GET** requests to the following:

* Stages
* Sponsors
* Artists
* ArtistMedia
* StageMedia
* SponsorMedia

**Note:** The ACL API now allows information to be selected on a per year basis. 
The earliest available year starts at 2012.

# Group Stage
Stage related resources of the Austin City Limits Project API

## Stages [/api/stages/]

The stage's *location* is assigned by a map of the festival.
The Stage resource represents a physical location in the Austin City Limits map.
(see http://theaustinites.pythonanywhere.com/stages/ for the mapping).
Note that depending on the year of the festival, a stage may have a different
sponsor sponsoring that stage or different artists playing on that stage.

+ Model (application/json)
    JSON representation of Stage resource.

    + Body
    
            {   
                [
                    ...,
                    
                   { "location": 1,
                     "years": [2012,2013,2014]
                   },
                   
                   ...
                ]
            }

### Retrieve all Stages [GET]
A GET request returns all stage locations and the years that stage location was involved in.
+ Response 200 (application/json)

    [Stages][]
    
## Stage [/api/stages/{location}/]

A single stage object. 

The Stage resource has the following attributes:

- location

The stage's *location* is assigned by a map of the festival.
The Stage resource represents a physical location in the Austin City Limits map.
(see http://theaustinites.pythonanywhere.com/stages/ for the mapping).
Note that depending on the year of the festival, a stage may have a different
sponsor sponsoring that stage or different artists playing on that stage.

+ Parameters
    + location (integer) ...  a number
    
+ Model (application/json)
    JSON representation of Stage resource.

    + Body
    
            {   "location": 1,
                "years": [2012,2013,2014]
            }

### Retrieve a single Stage [GET]

A GET request returns a json dictionary with string key "years"
and the integer years that the requested stage has been in use for the 
festival. The location is also included to be sure the response matches the request.

+ Response 200 (application/json)

    [Stage][]
        
## Stage Collection [/api/stages/{location}/{year}]

A stage collection returns information about it's *sponsor*
and *artists* that play on that stage location for the given year. 

+ Parameters
    + location (integer) ...  a number
    + year (integer) ... a year starting from 2012
    
+ Model (application/json)

        JSON representation of the Stage Collection Resource.  
        The Stage resources in the collections are embedded.

        + Body
            
            [
                {   "location": 1,
                    "year": 2014,
                    "sponsor": sponsor_id,
                    "artists": [id1,id2,...]
                }
            ]

### List Stage Information for a given year [GET]

A GET request for a **Stage Collection** returns the *location*, *year*, *sponsor id* for 
the requested stage location and year, as well as a *list of artist ids*
that have played on that stage during the requested year.
+ Response 200
    
    [Stage Collection][]
    
# Group Sponsor
Sponsor related resources of the **ACL API**


## Sponsors [/api/sponsors/]
    A JSON list of dictionaries returning all Sponsor information

+ Model (application/json)
    JSON representation of Sponsors resource.

    + Body
    
            [   
                ...,
                
                {
            
                "id": 42,
                "name": "Samsung Galaxy",
                "industry": "Mobile",
                "years": [2013,...],
                "stage_locations":[1,2,3,...]
                },
                
                ....
            ]   


### Retrieve all Sponsors [GET]
A *GET* request for all artists retrieves business information about that
sponsor as well as a list of years and stage locations each sponsor was involved in at ACL
+ Response 200 (application/json)

    [Sponsors][]

## Sponsor [/api/sponsors/{id}/]

A single sponsor object.

The Sponsor resource has the following attributes:

- id
- name
- industry

+ Parameters
    + id (integer) ... ID of the Sponsor in the form of a number
    
+ Model (application/json)
    JSON representation of Sponsor resource.

    + Body
    
            {
                "id": 42,
                "name": "Tito's Handmade Vodka",
                "industry": "alcohol industry"
                "years":[2012,2014],
                "stage_locations":[3,4,2]
            }

### Retrieve a single Sponsor [GET]

A GET request for a sponsor with given id returns 
the *id*, *name*, and *industry* the sponsor is associated with.
Note that sponsor names are unique. A list of years and stag locations are also given.
+ Response 200 (application/json)

    [Sponsor][]

## Sponsors Year [/api/sponsors/year/{year}]
Collection of all Sponsors that sponsored a Stage for the requested year.
**Note:** that a Sponsor may only sponsor at most one stage for any given year.
+ Model (application/json)

        JSON representation of the Sponsor Collection Resource.  
        The Sponsor resources in the collections are embedded.

        + Body
            
            [
                                ...,
                                
                                {
            
                                    "id": 42,
                                    "name": "Artist name",
                                    "industry": "Label of artist",
                                    "stage_location":1
                                },
                                
                               ...
            ]
                

            
### List All Sponsors for a given year[GET]

A GET request for SponsorYear returns a json dictionary with the year requested and the sponsors participating in that
given year.

+ Response 200
    
    [Sponsors Year][]

    
# Group Artist

Artist related resources of the **ACL API**

## Artists [/api/artists/]
    A JSON list of dictionaries returning all Artist information

+ Model (application/json)
    JSON representation of Artist resource.

    + Body
    
            [   
                ...,
                
                {
            
                "id": 42,
                "name": "Artist name",
                "label": "Label of artist",
                "origin": "Where the artist was from",
                "genre": "Genre of the artist",
                "years": [2013,...],
                "stage_locations":[1,2,3,...]
                },
                
                ....
            ]   


### Retrieve all Artists [GET]
A *GET* request for all artists retrieves music information about that
artist as well as a list of years and stage locations each artist has performed at ACL
+ Response 200 (application/json)

    [Artists][]


## Artist [/api/artists/{id}/]

A single Artist object with all its details
The Artist resource has the following attributes:

- id
- name
- label
- origin
- genre

The artist **id** is assigned by the ACL Project API at the moment of creation.

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the Artist to perform action with.

    
+ Model (application/json)
    A single JSON representation of Artist resource.

    + Body
    
            [   
                {
            
                "id": 42,
                "name": "Artist name",
                "label": "Label of artist",
                "origin": "Where the artist was from",
                "genre": "Genre of the artist",
                "years": [2013,...],
                "stage_locations":[1,2,3,...]
                
                }
            ]   


### Retrieve an Artist [GET]
A *GET* request for an artist retrieves music information about that
artist as well as a list of years and stage locations the artist has performed at ACL
+ Response 200 (application/json)

    [Artist][]

## Artists Year [/api/artists/year/{year}]
Collection of all Artists for a given year. **Note:** An artist can only play on one 
stage for any given year.

It **embeds** *Artist Resources* in the ACL Project API

+ Model (application/json)

        JSON representation of the Artist Collection Resource.  
        The Artist resources in the collections are embedded.

        + Body
            [
                     ...,
                                {
            
                                    "id": 42,
                                    "name": "Artist name",
                                    "label": "Label of artist",
                                    "origin": "Where the artist was from",
                                    "genre": "Genre of the artist",
                                    "stage_location": 5
                                },
                                
                      ...
                            
                
            ]

            
### List All Artists by Year [GET]
A GET request returns a json dictionary with an "artists" key whose value
is a list of artist ids and information for ACL in the requested year. The year requested is also included.
+ Response 200
    
    [Artists Year][]

# Group Media
Media related resources for Artist, Stage, and Sponsor

## ArtistMedia [/api/artists/{id}/media/]
A single ArtistMedia object with all its details

The ArtistMedia resource has the following attributes:

- artist
- bio
- photo
- youtube
- video
- twitter
- facebook
- twitterwidget
- youtubevideo
- webpage

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the ArtistMedia to perform action with.

    
+ Model (application/json)
    JSON representation of ArtistMedia resource.

    + Body
    
            {
             "artist" : 42,
             "bio" : "a description",
             "photo" : "url",
             "youtube"  "url",
             "video" : "url",
             "twitter" : "url",
             "facebook" : "url",
             "twitterwidget" : "twitter handle",
             "webpage" : "url"
            }
            
### Retrieve an ArtistMedia [GET]
**Note:** Some values of the attribute may not return a value depending on the available information given online.

+ Response 200 (application/json)

    [ArtistMedia][]

## SponsorMedia [/api/sponsors/{id}/media/]
A single SponsorMedia object with all its details

The SponsorMedia resource has the following attributes:

- sponsor
- bio
- photo
- youtube
- video
- twitter
- facebook
- twitterwidget
- youtubevideo
- webpage

+ Parameters
    + id (required, number, `1`) ... Numeric `id` of the SponsorMedia to perform action with.

    
+ Model (application/json)
    JSON representation of ArtistMedia resource.

    + Body
    
            {
             "sponsor" : 42,
             "bio" : "a description",
             "photo" : "url",
             "youtube"  "url",
             "video" : "url",
             "twitter" : "url",
             "facebook" : "url",
             "twitterwidget" : "twitter handle",
             "webpage" : "url"
            }
            
### Retrieve an SponsorMedia [GET]
**Note:** Some values of the attributes may not return a value depending on the available information given online.

+ Response 200 (application/json)

    [SponsorMedia][]
    
## StageMedia [/api/stages/{location}/media/{year}]
A single StageMedia object with all its details for the given year

The StageMedia resource has the following attributes:

- location
- name (usually a stage's name is just the sponsor's name prefixed to "stage")
- year
- bio
- photo
- youtube
- video
- twitter
- facebook
- twitterwidget
- youtubevideo
- webpage

+ Parameters
    + location (required, number, `1`) ... Numeric mapping of`location
    ` of the StageMedia to perform action with.
    + year (required, number, `2014`) ... requested year
    ` of the StageMedia to perform action with.

    
+ Model (application/json)
    JSON representation of StageMedia resource.

    + Body
    
            {
             "location" : 42,
             "name"  : "Honda Stage",
             "year"  : 2013,
             "bio" : "a description",
             "photo" : "url",
             "youtube"  "url",
             "video" : "url",
             "twitter" : "url",
             "facebook" : "url",
             "twitterwidget" : "twitter handle",
             "webpage" : "url",
            }
            
### Retrieve an StageMedia [GET]
**Note:** Some values of the attribute may not return a value depending on the available information given online.
Sponsor media may be used in the event a stage doesn't have the corresponding information.

+ Response 200 (application/json)

    [StageMedia][]
    
## StageMediaList [/api/stages/{location}/media/]
A list of StageMedia objects with all its details for the given stage location
The StageMedia resource has the following attributes:

- location
- name 
- year
- bio
- photo
- youtube
- video
- twitter
- facebook
- twitterwidget
- youtubevideo
- webpage

+ Parameters
    + location (required, number, `1`) ... Numeric mapping of`location
    ` of the StageMedia to perform action with.
    
+ Model (application/json)
    JSON representation of StageMedia resource.

    + Body
    
            [
                ...,
                {
                
                    "location" : 42,
                    "name"  : "Honda Stage",
                    "year"  : 2013,
                    "bio" : "a description",
                    "photo" : "url",
                    "youtube"  "url",
                    "video" : "url",
                    "twitter" : "url",
                    "facebook" : "url",
                    "twitterwidget" : "twitter handle",
                    "webpage" : "url",
                },
                ....
            ]
        
### Retrieve a list of StageMedia [GET]
**Note:** Some values of the attribute may not return a value depending on the available information given online.
Sponsor media may be used in the event a stage doesn't have the corresponding information.

+ Response 200 (application/json)

    [StageMediaList][]