Skip to content

Instantly share code, notes, and snippets.

@tylermilner
Last active March 27, 2017 15:55
Show Gist options
  • Save tylermilner/de3217f8fc3ad31da5429d149f879b73 to your computer and use it in GitHub Desktop.
Save tylermilner/de3217f8fc3ad31da5429d149f879b73 to your computer and use it in GitHub Desktop.
RadioStationAPI - Code & Tell Snippets
1.) Create 'api.raml' file:
#%RAML 1.0
title: Radio Station
version: v1
baseUri: http://api.samplehost.com
2.) Layout basic API structure:
/config:
get:
/login:
post:
/nowPlaying:
get:
put:
/shows:
get:
post:
/{id}:
get:
put:
delete:
/djs:
get:
post:
/{id}:
get:
put:
delete:
3.) Add details for '/shows' request/response payload types:
/shows:
get:
responses:
200:
body:
application/json:
post:
body:
application/json:
/{id}:
get:
responses:
200:
body:
application/json:
put:
body:
application/json:
delete:
responses:
204:
4.) Add type and example in POST '/shows' body:
post:
body:
application/json:
type: object
properties:
name: string
description: string
djId: string
broadcastInfo:
type: object
properties:
location: string
dayOfWeek: string
startTime: string
endTime: string
nextBroadcastTime: integer
avatarUrl: string
soundcloudUrl: string
example: |
{
"name": "The Greenroom",
"description": "A classically trained keyboardist and working musician based in Chicago, STUNNA (aka J. Cappo) has crafted his own unique sound within the fast paced world of Drum + Bass music",
"djId": "2",
"broadcastInfo": {
"location": "Chicago, IL, USA",
"dayOfWeek": "Wednesday",
"startTime": "14:00",
"endTime": "17:00"
},
"nextBroadcastTime": 1490814000,
"avatarUrl": "http://bassdrive.com/img/radio_schedule_entries/image/original/stunnagreenroompromo1nufinalhalf-74.jpg",
"soundcloudUrl": "https://soundcloud.com/stunna"
}
5.) Extract Show type to 'types' section:
types:
Show:
properties:
name: string
description: string
djId: string
broadcastInfo:
type: object
properties:
location: string
dayOfWeek: string
startTime: string
endTime: string
nextBroadcastTime: integer
avatarUrl: string
soundcloudUrl: string
6.) Implement "Show" type for the 'application/json'
post:
body:
application/json:
type: Show
example: |
{
"name": "The Greenroom",
"description": "A classically trained keyboardist and working musician based in Chicago, STUNNA (aka J. Cappo) has crafted his own unique sound within the fast paced world of Drum + Bass music",
"djId": "2",
"broadcastInfo": {
"location": "Chicago, IL, USA",
"dayOfWeek": "Wednesday",
"startTime": "14:00",
"endTime": "17:00"
},
"nextBroadcastTime": 1490814000,
"avatarUrl": "http://bassdrive.com/img/radio_schedule_entries/image/original/stunnagreenroompromo1nufinalhalf-74.jpg",
"soundcloudUrl": "https://soundcloud.com/stunna"
}
7.) Extract example to the 'type' section and convert from JSON to YAML syntax
types:
Show:
properties:
name: string
description: string
djId: string
broadcastInfo:
type: object
properties:
location: string
dayOfWeek: string
startTime: string
endTime: string
nextBroadcastTime: integer
avatarUrl: string
soundcloudUrl: string
example:
name: "The Greenroom"
description: "A classically trained keyboardist and working musician based in Chicago, STUNNA (aka J. Cappo) has crafted his own unique sound within the fast paced world of Drum + Bass music"
djId: "2"
broadcastInfo:
location: "Chicago, IL, USA"
dayOfWeek: "Wednesday"
startTime: "14:00"
endTime: "17:00"
nextBroadcastTime: 1490814000
avatarUrl: "http://bassdrive.com/img/radio_schedule_entries/image/original/stunnagreenroompromo1nufinalhalf-74.jpg"
soundcloudUrl: "https://soundcloud.com/stunna"
8.) Remove example from POST /shows:
post:
body:
application/json:
type: Show
9.) Use "Show" type in the rest of the "/shows" endpoints:
/shows:
get:
responses:
200:
body:
application/json:
type: Show[]
post:
body:
application/json:
type: Show
/{id}:
get:
responses:
200:
body:
application/json:
type: Show
put:
body:
application/json:
type: Show
delete:
responses:
204:
10.) Create "Collection" and "Member" 'resourceTypes':
resourceTypes:
Collection:
get:
responses:
200:
body:
application/json:
type: Show[]
post:
body:
application/json:
type: Show
Member:
get:
responses:
200:
body:
application/json:
type: Show
put:
body:
application/json:
type: Show
delete:
responses:
204:
11.) Apply "Collection" and "Member" to "/shows" endpoints:
/shows:
type: Collection
/{id}:
type: Member
12.) Make "Collection" and "Member" resourceTypes generic:
resourceTypes:
Collection:
get:
responses:
200:
body:
application/json:
type: <<item>>[]
post:
body:
application/json:
type: <<item>>
Member:
get:
responses:
200:
body:
application/json:
type: <<item>>
put:
body:
application/json:
type: <<item>>
delete:
responses:
204:
13.) Update the "/shows" endpoint to use the generic resourceTypes:
/shows:
type: { Collection: { item : Show } }
/{id}:
type: { Member: { item : Show } }
14.) Create "DJ" type with example:
DJ:
properties:
id: string
handle: string
firstName: string
lastName: string
showId: string
example:
id: "1"
handle: "Overfiend"
firstName: "Louis"
lastName: "Overfiend"
showId: "1"
15.) Update "/djs" endpoints:
/djs:
type: { Collection: { item : DJ } }
/{id}:
type: { Member: { item : DJ } }
16.) Add "Secured" trait:
traits:
Secured:
headers:
Authorization:
description: Authorization bearer header must contain the user session token.
example: Bearer aaaa.bbbb.cccc
responses:
401:
description: Indicates that the user session token is no longer valid. A new token should be obtained by logging in again.
17.) Apply "Secured" trait to POST/PUT/DELETE methods on "Collection" and "Member":
resourceTypes:
Collection:
get:
responses:
200:
body:
application/json:
type: <<item>>[]
post:
is: [Secured]
body:
application/json:
type: <<item>>
Member:
get:
responses:
200:
body:
application/json:
type: <<item>>
put:
is: [Secured]
body:
application/json:
type: <<item>>
delete:
is: [Secured]
responses:
204:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment