Model Hive

bzz kickstarts your development process by handling CRUD operations in your API for your registered models.

Currently bzz supports mongoengine, but support for other ORMs will be done soon. If you would like to see a different ORM supported, please create an issue for it.

What does Model Hive support

  • [POST] Create new instances;
  • [PUT] Update existing instances;
  • [DELETE] Delete existing instances;
  • [GET] Retrieve existing instances with the id for the instance;
  • [GET] List existing instances (and filter them);

All those operations also work in inner properties. What this means is that if your model has a many-to-one relationship to another model, you get free restful routes to update both.

ModelHive class

class bzz.model.ModelHive[source]
classmethod routes_for(provider, model, prefix='', resource_name=None)[source]

Returns the list of routes for the specified model.

  • [POST] Create new instances;
  • [PUT] Update existing instances;
  • [DELETE] Delete existing instances;
  • [GET] Retrieve existing instances with the id for the instance;
  • [GET] List existing instances (and filter them);
Parameters:
  • provider (Full-name provider or built-in provider) – The ORM provider to be used for this model
  • model (Class Type) – The model to be mapped
  • prefix (string) – Optional argument to include a prefix route (i.e.: ‘/api’);
  • resource_name (string) – an optional argument that can be specified to change the route name. If no resource_name specified the route name is the __class__.__name__ for the specified model with underscores instead of camel case.
Returns:

route list (can be flattened with bzz.flatten)

If you specify a prefix of ‘/api/’ as well as resource_name of ‘people’ your route would be similar to:

http://myserver/api/people/ (do a post to this url to create a new person)

Usage:

import tornado.web
from mongoengine import *
import bzz

server = None

# just create your own documents
class User(Document):
   __collection__ = "MongoEngineHandlerUser"
   name = StringField()

def create_user():
   # let's create a new user by posting it's data
   http_client.fetch(
      'http://localhost:8890/user/',
      method='POST',
      body='name=Bernardo%20Heynemann',
      callback=handle_user_created
   )

def handle_user_created(response):
   # just making sure we got the actual user
   try:
      assert response.code == 200, response.code
   finally:
      io_loop.stop()

# bzz includes a helper to return the routes for your models
# returns a list of routes that match '/user/<user-id>/' and allows for:
routes = bzz.ModelHive.routes_for('mongoengine', User)

User.objects.delete()
application = tornado.web.Application(routes)
server = HTTPServer(application, io_loop=io_loop)
server.listen(8895)
io_loop.add_timeout(1, create_user)
io_loop.start()

Errors

In the event of a POST, PUT or DELETE, if the model being changed fails validation, a status code of 400 (Bad Request) is returned.

If the model being changed violates an uniqueness constraint, bzz will return a status code of 409 (Conflict), instead.

Supported Providers

MongoEngine provider

Provider that supports the rest operations for the MongoEngine ORM.

Allows users to override get_instance_queryset and get_list_queryset in their models to change how queries should be performed for this provider. Both methods should return a mongoengine queryset and receive as arguments:

  • get_instance_queryset - model type, original queryset, instance_id and the tornado request handler processing the request
  • get_list_queryset - original queryset and the tornado request handler processing the request