Tutorial — Cosmic 0.4.2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Cosmic 0.4.2 documentation »

# Tutorial

## Step 1: Single-function API

In the spirit of Flask, let’s start with something you can copy and paste into a file, say `words.py`:

    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()

Run it:

    $ 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

See also

REST via Models

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 by subclassing `Server` and `APIClient`.

See Authentication for an example.

### Navigation

- index
- modules |
- next |
- previous |
- Cosmic 0.4.2 documentation »