README.md

rivr-rest

A library for building REST APIs with rivr.

Installation

$ pip install rivr-rest

Example

An example resource representing the repository for rivr.

class RepositoryResource(Resource):
    uri_template = '/repositories/rivr'

    def get_attributes(self):
        return {
            'name': 'Rivr',
            'description': 'Elegant microweb framework',
        }

When you request this resource as JSON, it will be serialized as the following:

{
    "name": "Rivr",
    "description": "Elegant microweb framework",
    "url": "/repositories/rivr"
}

It can be serialized to JSON HAL:

{
    "_links": {
        "self": { "href": "/repositories/rivr" }
    },
    "name": "Rivr",
    "description": "Elegant microweb framework"
}

We can define another resource with a relation to the repository as follows:

class UserResource(Resource):
    uri_template = '/kyle'

    def get_attributes(self):
        return {
            'name': 'Kyle',
        }

    def get_relations(self):
        return {
            'repository': RepositoryResource()
        }

This relation will automatically be embedded in the JSON representation:

{
    "name": "Kyle",
    "repository": {
        "name": "Rivr",
        "description": "Elegant microweb framework",
        "url": "/repositories/rivr"
    }
}

Along with HAL:

{
    "name": "Kyle",
    "_embedded": {
        "repository": [
            {
                "_links": {
                    "self": { "href": "/repositories/rivr" }
                },
                "name": "Rivr",
                "description": "Elegant microweb framework"
            }
        ]
    }
}

You can opt-out of the automatic embedding of our resources:

def can_embed(self, relation):
    return False

Now when we serialize the resource, the relations will instead be links:

{
    "name": "Kyle",
    "repository_url": "/repositories/rivr"
}

Content Types

rivr-rest has support for the following content types using content negotiation:

• JSON (application/json)
• HAL JSON (application/hal+json)
• Siren JSON (application/vnd.siren+json)
• HTML (text/html)

See Also

• rivr-rest-peewee - Resource extensions for building APIs with the Peewee ORM.

License

rivr-rest is released under the BSD license. See LICENSE.