1. Getting Started¶
We have battle tested prestans under Apache (using mod_wsgi) and Google’s AppEngine platform.
Code samples used throughout our documentation is available as a Google AppEngine project, we highly recommend you grab a copy so you can see how it all fits in.
You will require a copy of Google’s AppEngine Python SDK (v1.7.0+) to run the sample project.
Our philosophy is “take as much or as little of the project as you like”, prestans was designed ground up to sit nicely along side other Python frameworks. Needless to say that a dynamic language such as Python lends itself extremely well to writing frameworks such as prestans, and highly scaleable Web applications.
And incase you are still wondering prestans is a latin word meaning “excellent, distinguished, imminent”.
- Validation or incoming and outgoing using strongly defined Models
- Pluggable architecture allowing prestans to plug into any authentication, caching and serialization requirements.
- A custom URL dispatcher that allows you to re-use handlers for multiple output formats.
- Data Adapters, that allows you to translate persistent objects into REST resources, with a single line of code.
- Validation of URL parameters using strong defined Parameter Sets.
- Dynamically filtering response fields when writing responses to reduce payload sizes.
- Auto generate API documentation using Blueprint (Utilities)
We also maintain a set of tools that leverages prestans’s
Model definition schema to generate boiler plate client side parsing of REST resources.
We recommend installing prestans via PyPI:
$ pip install prestans
this will build and install prestans for your default Python interpreter.
Alternatively you can download and build prestans using distutils:
$ tar -zxvf prestans-1.1.tgz $ cd prestans-1.1 $ python setup.py install
Environments like Google’s AppEngine require you to include custom packages as part of your source. Things to consider when distributing prestans with your application:
- Make sure you target a particular release of prestans, distributing our development branch is not recommended.
- If you prefer reference prestans as a Subversion external, ensure you use reference one of the
tags, it is not recommended to reference
- If your server environment has hard limits on number of files, consider using zipimport.
1.2.1. Software Requirements¶
The server side requires a WSGI compliant environment:
- Python 2.6+, 2.7 recommended
- WSGI compliant server environment (Apache + mod_wsgi, or Google AppEngine, etc).
- Python Paste components (e.g WebOb)
Client side code is written for Google Closure.
Before you begin building REST services with prestans, it’s important that you understand it’s key concepts.
Serializers are pluggable components that pack and unpack REST data in a seriazable format. For performance reasons most of them are wrappers on existing Python libraries, there’s nothing stopping you from implementing one purely in Python.
You should never have to serialize or unserialize data when writing prestans apps, this is soley a job for the serializers. If serialization or unserialization fails, exceptions are raised and prestans sends out a canned error message to the client.
We are working on XML support, and might settle for AtomPub.
1.3.2. REST Application¶
REST Application is our router, an instance of REST Application is responsible for mapping URLs to handlers. It’s also responsible managing the API call lifecycle and humanising error messages for the client.
REST Application can not be used directly, you must use a sub class that’s been paired with a Serializer. Out of the box prestans provides the following REST Application routers:
It’s possible to write your serializer and REST Application, you should only have to do this if you want to use a format not supported by prestans.
Handlers are end points where an API request URL maps to. It’s here that your business logic should live and how prestans knows where to hand over to your code. A handler maps to a URL pattern. Handlers should define an instance method for each HTTP method that you want to support.
Regex matched patterns are passed to your handler functions as parameters. Handlers can choose to use RequestParsers to validate incoming requests.
Models are a set of rules that can be used by a prestans parser to validate the body of the request. Models are also use to validate and even auto generate responses from persistent data models.
prestans Models descriptions are quite similar to Django or Google AppEngine models.
Attributes can be of the following types, these are in accordance with popular serialization formats for REST APIs:
- Date Time
Each attribute provides a set rules configured by you, that prestans uses to validate incoming and outgoing data.
1.3.5. Request Parsers¶
Request Parsers allow you to define a set of rules that a request handler can use to validate incoming and outgoing data. Rules are define per HTTP method each handler corresponds supports and allows you to:
- validate sets of parmaeters in the URL
- the body of the request (for
DELETEmethods) by defining Models
- a response attribute list template which allows clients to request partially formed responses, the template directly corresponds to the definition of the handler’s response format
- a definition of acceptable partially formed requests (based on models)
Complimentary to Request Parsers are
ParameterSet which allow you defined patterns of acceptable groups of parameters in the URL and
AttributeFilter which allow you to make exceptions to the rules defined by Models.
1.3.6. Data Adapters¶
Data Adapters are a set of extensions that allow you to quickly turn persistent data objects into instances of your REST models. prestans allows serialization of prestans managed Data Types, see Models. Data Adapters are backend specific (we currently support SQLAlchemy <http://www.sqlalchemy.org>_, AppEngine NDB <https://developers.google.com/appengine/docs/python/ndb>_).
These Adapters function map persistent models against prestans Models using a registry, allowing prestans to perform the translation to construct your REST handler’s response.
prestans was designed ground up to live along side other Python Web development frameworks, and work under any WSGI compliant environment. This presents us with a challenge of fitting into services that may already be in use by your application or environment.
Providers are wrappers that present prestans with an standardised way to talk to these environment specific services. The provider implements specific code to return the status that prestans expects.
We provide extensive documentation on writing your own providers for environments we don’t support out of the box.
These services include: