Tutorial

Step 1: Single-function API

Before we get into the features, let’s create a blank API to see how an API is served and consumed. Here it is:

from cosmic.api import API
from cosmic.types import *

words = API('words')


@words.action(accepts=String, returns=String)
def pluralize(word):
    if word.endswith('y'):
        return word[:-1] + 'ies'
    else:
        return word + 's'

if __name__ == "__main__":
    words.run()

Save this as words.py and run:

$ python words.py
* Running on http://127.0.0.1:5000/

Now we can interact with the API:

$ curl -i -X POST -H 'Content-Type: application/json' -d '"pony"' http://127.0.0.1:5000/actions/pluralize
HTTP/1.0 200 OK
Content-Type: application/json

"ponies"

Did you notice the type definitions above? They help validate the data:

$ curl -i -X POST -H 'Content-Type: application/json' -d '1' http://127.0.0.1:5000/actions/pluralize
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{"error": "Invalid String: 1"}

Step 2: Making a REST Model

Here’s a simple model:

from cosmic.models import BaseModel
from cosmic.exceptions import NotFound

@words.model
class Word(BaseModel):
    methods = ['get_by_id']
    properties = [
        required(u"letters", String)
    ]
    @classmethod
    def get_by_id(cls, id):
        if id == "0":
            return {"letters": "hello"}
        else:
            raise NotFound
$ curl -i -H 'Content-Type: application/json' http://127.0.0.1:5000/Word/0
HTTP/1.0 200 OK
Content-Type: application/json

{"letters": "hello", "_links": {"self": {"href": "/Word/0"}}
$ curl -i -H 'Content-Type: application/json' http://127.0.0.1:5000/Word/1
HTTP/1.0 404 NOT FOUND

Step 3: Authenticating

By default, all models and actions are accessible to all clients. To restrict access you use authentication and authorization. Cosmic doesn’t currently support or recommend a particular method of authentication. However, it allows you to implement your own via client_hook and Server.

See Authentication for an example.