teal api docs

## API Documentation
All API requests are made to the hostname `https://api.teal.cool`. The API response is not guaranteed when using http. Teal is configured to use [modern ciphers only](https://mozilla.github.io/server-side-tls/ssl-config-generator/?server=nginx-1.9.5&openssl=1.0.1e&hsts=yes&profile=modern) with HTTPS.
### Versioning
Teal web API is not currently versioned. 
### Rate Limiting/Bursting

The API enforces a rate limit of around 3 requests/sec per IP. Bursting is provided as a convenience and for speedier uploads. Continuous usage above the rate limit might return a 403 status code.

### Authentication and Authorization
Authorization on Teal is done either using cookies or keys passed through request headers.
#### Authentication
Authentication is required for performing create, update or delete actions, but not required to read. Some meta information (such as owners) might be provided to authenticated and authorized users and not others. Episodes that have upcoming publishing dates also might only be shown to authenticated and authorized users.

Every account is authenticated over email:

```
curl -X POST -d '{"email":"<YOUR EMAIL>"}' https://api.teal.cool/login
```

or using the shortcut version:

```
curl -X POST https://api.teal.cool/login?email=<YOUR EMAIL>
```

The login method doesn't return any useful information. Once an email is sent, it will expire in 8 minutes. During this time, you can not request an other authentication email.

When you open your email account you will see an email from login@teal.cool. At this point, you can choose to also login using the frontend. If you do, your key will be accessible at `api.teal.cool/key` from your browser. Note that every time you request a key, the old one will be invalidated.

You can also choose only to get your key directly:

```
curl https://api.teal.cool/auth?token=aZ3vNUb0Rjm7gBK4BeBjgg
```
API keys will never expire but every successful login will generate a new one.

#### Authorization
To perform actions, you will need to call requests with the `teal-api-key` HTTP header. Alternatively you can call it with a cookie that was passed on authentication. If successful, all responses will return the `teal-logged-in-as` HTTP header, which will be your email. Alternatively, calling `api.teal.cool/whoami` will return the email of the user.


### Models
Program is the only top level model. A program can have many episodes, an episode can have many tracks. When a program is returned, a an array of its episodes are also returned in abbreviated form. When an episode is returned by itself, it is returned with an abbreviated form of its program and all of its tracks.
#### Program
A program looks like this:
```
{
	"active": true,
	"author": "Ted and Renan",
	"copyright": "Renan and Ted",
	"cover_image": "http://i.imgur.com/Lcychlc.png",
	"description": "An overall great program!",
	"image": "http://i.imgur.com/1iQ6U4d.png",
	"itunes_categories": [...],
	"language": "en-us",
	"name": "DD-MM-YYYY",
	"organizations": ["WJRH"],
	"owners": ["renandincer@gmail.com"],
	"redirect_url": null,
	"scheduled_time": null,
	"shortname": "sendnudes",
	"stream": "listen.wjrh.org",
	"subtitle": "Ted and Renan play music",
	"tags": ["music"],
	"id": "56e7675ce2b026000a0ec5f6",
	"episodes": [...]
}
```
 A program's episodes is returned (not shown above) with some details left out. The id attribute from the show can be used to request the full episode object
 
#### Episode
An episode looks like this:
```
{
	"audio_url": "http://api.teal.cool/download/56e76edfc49c530010f9a2e5.mp3",
	"description": "Ted really likes his Jazz (These Foolish Things). Ted's friend Kate calls in. Renan dances to Beirut (but you don't see this). Ted likes cheese? Everyone's happy today.",
	"end_time": "2016-03-15T03:02:41.824+00:00",
	"guid": "025de47f-52e4-47ad-80d1-87164094150c",
	"image": "",
	"length": "3212",
	"name": "14-03-2016",
	"pubdate": "2016-03-15T02:09:25.228+00:00",
	"start_time": "2016-03-15T02:09:39.896+00:00",
	"tracks": [...], #episode's tracks - see track object
	"type": "audio/mpeg",
	"id": "56e76edfc49c530010f9a2e5",
	"program": {}
}
```
 An episode's program is returned (not shown above) with some details left out. The shortname attribute from the show can be used to gather full show.

#### Track
A track looks like this:
```
{
	"artist": "Beirut",
	"log_time": "2016-03-15T02:54:02.016+00:00",
	"mbid": "2984729d-fb43-420b-9d03-d9e34562d843",
	"title": "Elephant Gun",
	"id": "56e77948c49c530020f9a2e6"
}
```
A track can only be retrieved with an episode.

### Using Programs
In order to get programs you own you can run the following:
```
curl --header "teal-api-key: thisisakeykeykey" https://api.teal.cool/programs
```
As a result, you will get an array of programs.
#### Creating a program
In order to create a program make a HTTP POST request to `/programs` with your program in valid JSON format. A simple example would be:
```
curl --header "teal-api-key: thisisakeykeykey" -X POST -d '{"name":"Example Show"}' https://api.teal.cool/programs
```
When submitted Teal will respond with the created object in JSON and a 200 OK status code. A program will not be created if there is a program with the same shortname already existing (in the example above Teal would assume the shortname requested is `example-show`. To circumvent this, once can specify a shortname upon creation:
```
curl --header "teal-api-key: thisisakeykeykey" -X POST -d '{"name":"Example Show", "shortname":"greatawesomeshow"}' https://api.teal.cool/programs
```
If created successfully, the response will be 200 OK and the created object.
Once can later view the program by navigating to the program. A program will now be visible to all with the url similar to below:
```
curl https://api.teal.cool/programs/greatawesomeshow
```