Welcome to ripozo’s documentation!¶
Contents:
ripozo¶

A pluggable tool for quickly and efficiently creating web apis. In the modern day, your server is no longer just interacting with a web browser. Instead it’s interfacing with desktop and mobile web browsers, multiple native applications, and maybe even being exposed as an API to other developers. Ripozo is designed to solve this problem. It allows you to easily build Hypermedia/HATEOAS/REST APIs quickly and efficiently.
NOTE: ripozo is under rapid development until version 1.0.0. It is not considered stable until that point.
Installation¶
pip install ripozo
Example¶
from ripozo.decorators import apimethod
from ripozo.dispatch.adapters import SirenAdapter, HalAdapter
from ripozo.viewsets import ResourceBase
# import the dispatcher class for your preferred webframework
class MyResource(ResourceBase):
@apimethod(methods=['GET'])
def say_hello(cls, request):
return cls(properties=dict(hello='world'))
# initialize the dispatcher for your framework
# e.g. dispatcher = MyDispatcherImplementation()
dispatcher.register_adapters(SirenAdapter, HalAdapter)
dispatcher.register_resources(MyResource)
And just like that, you have an api that can return either Siren or Hal formatted responses. Pretty easy, right?
Philosophy¶
Hypermedia¶
Ripozo is designed first and foremost behind the belief that Hypermedia APIs are the way everything should be developed. With hypermedia APIs and good client consumers, boilerplate code is removed and a developer is free to focus on making the difficult decisions and writing the business logic, not the boiler plate code. It should be noted that ripozo goes beyond CRUD+L. CRUD+L is a good step in the right direction, but it still requires too much knowledge on the client side still. With true Hypermedia, the client doesn’t need to how to construct URLs or what the actions available on a given resource are. The server can simply tell you.
Unopinionated (unless you want it to be)¶
Ripozo doesn’t make design decisions for you. Ripozo is a tool that is capable of being used in any existing web framework. It can be used with any database. Any Hypermedia protocol can be used. If you really wanted to, though we don’t recommend it, you could even render raw HTML with a tool like Jinja2. You could even theoretically skip the web application all together and use it directly instead of through a web api. Long story short, Ripozo doesn’t care how it is used. It can be plugged in for a small part of your application or used exclusively.
Extensible and Pluggable¶
Ripozo is extensible/pluggable. Just because ripozo itself doesn’t make design decisions for you doesn’t mean that it shouldn’t be batteries included, we just believe that the batteries included versions should be split out into other packages. Hence its extensibility. There are already packages that make it easy to use both Cassandra and SQL databases via cqlengine and SQLAlchemy. There’s an adaption of ripozo for integration with Flask. We didn’t want to make design decisions for you. But we figured that if you wanted something more opinionated, we’d make it easy to extend ripozo. As a side note, we really hope that you open source any ripozo based packages that you create and let us know. After all, let’s keep our open source world DRY.
Basic Concepts¶
Alright, so you’re probably tired of hearing about all our self righteous talk about ripozo’s philosophy and want to know how you can actually use it to start building awesome APIs. Ripozo has four basic pieces: Dispatchers, Adapters, Resources, and Managers. tl:dr; version: Dispatchers handle incoming requests and direct them to Resources. Resources perform the business logic, optionally using a Manager to interact with a database. The Resource returns an instance of itself to the dispatcher which determines which Adapter to use. The adapter then takes the Resource instance and formats it into an appropriate response. The dispatcher then returns this response.
Now for the more detailed descriptions...
Dispatchers¶
In this base ripozo package, the dispatcher is simply an abstract base class with a few convience methods. Since the handling of incoming requests is dependent on the framework you are using, and we don’t want to make design decisions for you, we thought that this would be a bad place for making opinionated decisions. However, the upside is that it is very easy to create dispatchers. In fact, a Flask dispatcher has already been created and is only one file less than 100 lines long. In the future we will be adding more webframework specific dispatchers and plan on making a framework of our own that is specific to ripozo.
Resources¶
Resources are the bread and butter of ripozo. They determine the business logic of an application. Resources should be reusable across all ripozo dispatch and manager extensions. In other words, you should be able to take your ripozo resources that you originally developed for Flask and plug them into a Django application.
Managers¶
Managers are more or less the state keepers of the application.
Adapters¶
Adapters determine the format in which to return a response. They take a resource instance and generate what the response should look like. For example, you could have an adapter that returns a SIREN response and another adapter that returns a HAL response. The best part is, that these are entirely reusable. That means that you can support as many adapters as are written by anyone in the world with no extra work on your part outside of installing the extra adapter packages. This is extemely useful because you can write your logic once and not have to worry about duplicating your code so that the front-end web team can use SIREN and the mobile team can use basic CRUD+L.
Versioning¶
Until version 1.0.0 ripozo is an unstable state and the version follows sentimental versioning. After that the versioning will follow a standard major.minor.patch style.
- patch: forwards and backwards compatible
- minor: backwards compatible
- major: No guarantees
Contributing¶
Want to help out? We’d love it! Github will be the hub of development for ripozo. If you have any issues, comments, or complaints post them there. Additionally, we are definitely accepting pull requests (hint: we almost always love more tests and documentation). We do have just a few requests:
- Every method, function, and docstring should have a thorough docstring
- There should be at least one unit test for each function and method
- Keep your pull requests to one issue. (Preferably open an issue on github first for record keeping)
CHANGELOG¶
0.1.27 (unreleased)¶
- Nothing changed yet.
0.1.26 (2015-04-23)¶
- Added base_url_sans_pks classproperty to ResourceBase
- Create is now an individual resource rather than a list resource
- Added CreateRetrieve, CreateRetrieveUpdate, andCreateRetrieveUpdateDelete mixins
- Removed CreateRetrieveList mixin
0.1.25 (2015-04-16)¶
- Overhauled how links and relationships are generated
- Lots of bugs
- Added include_relationships keyword argument to ResourceBase __init__ for performance reasons
0.1.24 (2015-04-13)¶
- Nothing changed yet.
0.1.23 (2015-04-13)¶
- Changed location of classproperty decorator from
ripozo.utilities
toripozo.decorators
- Fixed bug with wrapping _apiclassmethod decorated functions.
0.1.22 (2015-04-10)¶
- Fixed error with formatting exceptions
0.1.21 (2015-04-07)¶
- Added links
- Added _list_fields attribute to BaseManager for more efficient querying when necessary
- Moved getting the adapter class based on the format type in the dispatcher to its own method.
0.1.20 (2015-03-24)¶
- Fields no longer have a default.
- Adapter.extra_headers returns a dictionary instead of a list
- Fields can specify an error message.
- ListField added
- Fixed deep inheritance issue with translate decorator.
- Added the name of the relationship as an item in the rel list in the SIREN adapter.
0.1.19 (2015-03-16)¶
- Endpoint name
0.1.18 (2015-03-16)¶
- Fixed bug with RetrieveList mixin
- Added
picky_processor
which specifically includes processors to include or exclude. - pre and post processors now get the name of the function being called. before running
0.1.17 (2015-03-16)¶
- Fucked up...
0.1.16 (2015-03-16)¶
- Fixed the bug where inheritance of abstract methods resulted in mutable common endpoint_dictionaries
- endpoint_dictionary is now a method and not a property
0.1.15 (2015-03-16)¶
- Fixed bug that resulted in multiple forward slashes in a row on a url
0.1.14 (2015-03-16)¶
- Added method to RequestContainer object
- Imported Relationship and ListRelationship into relationships.__init__.py module for more intuitive access
- Imported HtmlAdapter to adapters.__init__.py for more intuitive imports.
- Including html adapter templates in package
0.1.13 (2015-03-14)¶
- Added generic CRUD+L mixins. These are included merely for convience
- Required fields validation can be skipped. In other words, you can now specify that a field does not need to be present when validating
0.1.12 (2015-03-14)¶
- Code cleanup
0.1.11 (2015-03-08)¶
- Some updates to the release process.
0.1.10 (2015-03-08)¶
- Started using zest.releaser for managing releases.
- Added
register_resources
method to the DispatcherBase class