from IPython.display import Image

Image(filename='api-console-snapshot.png')

Image(filename='api-console-snapshot-resp.png')

"""
Explanation: RAMLfications
Lynn Root
Backend Engineer @ Spotify
@roguelynn
What Is RAML?
RAML stands for RESTful API Modeling Language. 
Very similar to Swagger and Blueprint, it's used to describe REST APIs.
What it looks like:
```yaml
%RAML 0.8
title: Spotify Web API
version: v1
baseUri: https://api.spotify.com/{version}
mediaType: application/json
documentation:
  - title: Spotify Web API Docs
    content: |
      Welcome to the Spotify Web API specification. For more information about
      how to use the API, check out developer site.
/albums:
  displayName: several-albums
  get:
    description: |
      Get Several Albums
    queryParameters:
      ids:
        displayName: Spotify Album IDs
        type: string
        description: A comma-separated list of IDs
        required: true
        example: "382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo,2noRn2Aes5aoNVsU6iWThc"
      market:
        displayName: Market
        description: The market (an ISO 3166-1 alpha-2 country code)
        type: string
        example: ES
        required: false
    responses:
      200:
        body:
          application/json:
            example: !include example/get-albums-example.json  
```
Why?
Why a description language for your API?


Have a single source-of-truth reference for your API


Machine & human-ish readable


Clear definition of own versioned API specification


Why RAML?


not limited to describing in JSON (Swagger only supports JSON Schema)


Can support different API versioning (Blueprint can as well)


Include sample representations (Blueprint can as well)


Allows for including of external files from either local filesystem or via an HTTP request - no need for one massive .raml file (Neither Swagger nor Blueprints supports this)


It's not WADL


Why did Spotify choose RAML


"new kid on the block" & very active development - also means it's very young


more readable from our PoV

actual syntax & file structure
external file inclusions 



open-source spec


Setting the scene
I hated answering repeated questions
So I built a thing
It takes our RAML file
And makes an interactive console
End of explanation
"""


!pip install ramlfications

"""
Explanation: enter: RAMLfications
TL;DR: Python reference implementation for RAML
Let's play:
bash
$ pip install ramlfications
End of explanation
"""


from ramlfications import parse

RAML_FILE = "spotify-web-api.raml"
api = parse(RAML_FILE)

api

#metadata
api.title

api.version

api.base_uri

api.protocols

# security schemes
api.security_schemes

oauth = api.security_schemes[0]
oauth.settings.get("scopes")

# API endpoints
res = api.resources
res

get_an_album = res[1]
get_an_album.uri_params

get_an_album.method

get_an_album.description

get_an_album.description.html

get_an_album.display_name

get_an_album.path

get_an_album.absolute_uri

# parameters
uri_param = get_an_album.uri_params[0]
uri_param.name

uri_param.required

uri_param.example

get_an_album.parent

# API traits
api.traits

paged = api.traits[1]
paged.query_params

query_param = _[0]

query_param.name

query_param.raw

"""
Explanation: using RAMLfications within your library
End of explanation
"""


!ramlfications validate spotify-web-api.raml

!ramlfications validate invalid.raml

"""
Explanation: fun from the command line
validate your RAML file
End of explanation
"""


!ramlfications validate --config raml_config.ini invalid.raml

"""
Explanation: Your API does in fact support FTP?
Just add it to your config file!
bash
$ cat raml_config.ini
ini
[custom]
protocols = FTP
End of explanation
"""


!ramlfications tree spotify-web-api.raml

# MOAR!
!ramlfications tree spotify-web-api.raml -v

# I want MOAR
!ramlfications tree spotify-web-api.raml -vv

# I WANT MOOOOARRRRR
!ramlfications tree spotify-web-api.raml -vvv

"""
Explanation: visualize your RAML file
End of explanation
"""


