A RAML codec for Core API.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
etc
raml_codec
tests
.gitignore
.travis.yml
LICENSE.md
MANIFEST.in
README.md
requirements-unfrozen.txt
requirements.txt
runtests
setup.py
tox.ini

README.md

RAML Codec

A RAML codec for Core API.

travis-image pypi-image

Introduction

This is a Python Core API codec for the RAML schema format.

It currently supports RAML 0.8.

Installation

Install using pip:

$ pip install raml-codec

Using with the Python Client Library

Install coreapi and the raml-codec.

$ pip install coreapi
$ pip install raml-codec

To use the Python client library to interact with a service that exposes a Swagger schema, include the codec in the decoders argument.

>>> from raml_codec import RAMLCodec
>>> from coreapi.codecs import JSONCodec
>>> from coreapi import Client
>>> decoders = [RAMLCodec(), JSONCodec()]
>>> client = Client(decoders=decoders)

If the server exposes the schema without properly using an application/raml+yaml content type, then you'll need to make sure to include format='raml' on the initial request, to force the correct codec to be used.

>>> url = 'https://raw.githubusercontent.com/spotify/web-api/master/specifications/raml/api.raml'
>>> schema = client.get(url, format='raml')

At this point you can now start to interact with the API:

>>> client.action(schema, ['search-item'], params={'q': 'Deadmaus', 'type': 'artist'})

Using with the Command Line Client

Once the openapi-codec package is installed, the codec will automatically become available to the command line client.

$ pip install coreapi-cli
$ pip install openapi-codec
$ coreapi codecs show
Codec name   Media type                 Support              Package
corejson   | application/coreapi+json | encoding, decoding | coreapi==2.0.7
openapi    | application/raml+yaml    | encoding, decoding | raml-codec==0.1.0
json       | application/json         | decoding           | coreapi==2.0.7
text       | text/*                   | decoding           | coreapi==2.0.7
download   | */*                      | decoding           | coreapi==2.0.7

If the server exposes the schema without properly using an application/raml+yaml content type, then you'll need to make sure to include format=raml on the initial request, to force the correct codec to be used.

$ coreapi get https://raw.githubusercontent.com/spotify/web-api/master/specifications/raml/api.raml --format raml
<Spotify Web API "https://raw.githubusercontent.com/spotify/web-api/master/specifications/raml/api.raml">
    album(id, [market])
    album-tracks(id, [market], [limit], [offset])
    artist(id)
    artist-albums(id, [album_type], [market], [limit], [offset])
...

At this point you can start to interact with the API.

$ coreapi action search-item --param q="Deadmaus" --param type=artist
{
    "artists": {
        "href": "https://api.spotify.com/v1/search?query=Deadmaus&offset=0&limit=20&type=artist",
        "items": [
            {
                "external_urls": {
                    "spotify": "https://open.spotify.com/artist/2CIMQHirSU0MQqyYHq0eOx"
                },
                "followers": {
                    "href": null,
                    "total": 1496502
                },
                "genres": [
                    "big room",
                    "breakbeat",
...

Use the --debug flag to see the full HTTP request and response.

> GET /v1/search?q=Deadmaus&type=artist HTTP/1.1
> Accept-Encoding: gzip, deflate
> Connection: keep-alive
> Accept: application/coreapi+json, application/vnd.coreapi+json, */*
> Host: api.spotify.com
> User-Agent: coreapi
< 200 OK
< Access-Control-Allow-Credentials: true
< Access-Control-Allow-Headers: Accept, Authorization, Origin, Content-Type
< Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, DELETE
< Access-Control-Allow-Origin: *
< Access-Control-Max-Age: 604800
< Cache-Control: public, max-age=7200
< Connection: keep-alive
< Content-Encoding: gzip
< Content-Type: application/json; charset=utf-8
< Date: Tue, 27 Sep 2016 11:27:07 GMT
< Keep-Alive: timeout=600
< Server: nginx
< Strict-Transport-Security: max-age=31536000;
< Transfer-Encoding: chunked
< X-Content-Type-Options: nosniff
<
< {
<   "artists" : {
<     "href" : "https://api.spotify.com/v1/search?query=Deadmaus&offset=0&limit=20&type=artist",
<     "items" : [ {
...