Prestans Documentation Release 2.0 Anomaly Software November 02, 2016 Contents 1 Installation 3 1.1 Software Requirements.........................................3 1.2 Deployment notes............................................4 1.2.1 Apache + mod_wsgi......................................4 1.2.2 AppEngine...........................................4 1.3 Unit testing................................................4 2 Framework Design 7 2.1 Exceptions................................................7 2.2 HTTP Header Reference.........................................7 2.2.1 Content Negotiation.......................................8 2.2.2 Custom headers.........................................8 3 Routing & Handling Requests 11 3.1 Serializers & DeSerializers........................................ 11 3.2 Routing Requests............................................. 12 3.2.1 Regex & URL design primer.................................. 12 3.2.2 Using Request Router...................................... 13 3.3 Handling Requests............................................ 14 3.4 Constructing Response.......................................... 17 3.4.1 Minifying Content....................................... 18 3.4.2 Serving Binary Content..................................... 18 3.5 Raising Exceptions............................................ 19 3.5.1 Unsupported Vocabulary or Content Type........................... 19 3.5.2 Configuration Exceptions.................................... 19 3.5.3 Data Validation Exceptions................................... 20 3.5.4 Parser Exceptions........................................ 20 3.5.5 Handler Exceptions....................................... 21 4 Validating Requests & Responses 23 4.1 Attribute Filters.............................................. 23 4.2 Setting up validation rules........................................ 24 4.3 Working with parsed data........................................ 25 4.3.1 Parameters Sets......................................... 25 4.3.2 Request Body.......................................... 26 4.3.3 Response Body......................................... 27 5 Types & Models 29 i 5.1 Writing Models.............................................. 30 5.1.1 Defining Attributes....................................... 31 5.1.2 To One Relationship...................................... 31 5.1.3 To Many Relationship (using Arrays)............................. 32 5.1.4 Self References......................................... 32 5.2 Special Types............................................... 32 5.2.1 DateTime............................................ 33 5.2.2 DataURLFile.......................................... 33 5.3 Using Models to write Responses.................................... 33 5.4 Type Configuration Reference...................................... 34 5.4.1 String.............................................. 34 5.4.2 Integer.............................................. 34 5.4.3 Float............................................... 35 5.4.4 Boolean............................................. 35 5.4.5 DataURLFile.......................................... 35 5.4.6 Date............................................... 36 5.4.7 Time............................................... 36 5.4.8 DateTime............................................ 36 5.5 Collections................................................ 37 5.5.1 Array.............................................. 37 5.5.2 Model.............................................. 37 6 Providers 39 6.1 Authentication.............................................. 39 6.1.1 Fitting into your environment.................................. 39 6.1.2 Writing your own provider................................... 40 6.1.3 Working with Google AppEngine............................... 41 6.1.4 Attaching AuthContextProvider to Handlers.......................... 41 7 Data Adapters 43 7.1 Pairing REST models to persistent models............................... 43 7.2 Adapting Models............................................. 45 7.3 Writing your own DataAdapter..................................... 46 8 Google Closure Library Extensions 49 8.1 Installation................................................ 49 8.1.1 Unit testing........................................... 50 8.2 Extending JavaScript namespaces.................................... 50 8.3 Types API................................................ 51 8.3.1 Array.............................................. 51 8.3.2 Attribute Change Events.................................... 52 8.3.3 Generating Model Code.................................... 53 8.4 REST Client............................................... 53 8.4.1 Request Manager........................................ 54 8.4.2 Composing a Request...................................... 54 8.4.3 Dispatching a Request..................................... 56 8.4.4 Working with Responses.................................... 56 8.4.5 Xhr Communication Events.................................. 57 9 Thoughts on API design 59 9.1 REST resources are not persistent models................................ 59 9.2 Collections & Entities.......................................... 59 9.3 Response Size.............................................. 60 10 Reference Material 61 ii 10.1 WSGI & REST.............................................. 61 10.2 HTTP................................................... 61 10.3 Advanced Python............................................. 61 10.4 Serialization format........................................... 62 10.5 Server Software............................................. 62 10.6 Developer Tools............................................. 62 11 Feedback 63 12 Discussions 65 13 License 67 iii iv Prestans Documentation, Release 2.0 Prestans is a WSGI (PEP-333) complaint micro-framework that allows you to rapidly build quality REST services by introducing a pattern of models, parsers and handlers and in turn taking care of boilerplate code. Prestans sits better with complex Ajax applications written with JavaScript infrastructure like Google Closure, or native mobile apps. Prestans is currently hosted on Github and distributed under the terms defined by the New BSD license. A list of current downloads is available here. We highly recommend using PyPI to install Prestans. This document assumes that you have a working knowledge of REST and WSGI. Contents 1 Prestans Documentation, Release 2.0 2 Contents CHAPTER 1 Installation For a typical server production deployment, we recommend installing Prestans via PyPI: $ sudo pip install prestans this will build and install Prestans for your default Python interpreter. To keep up-to-date; use the ---upgrade option: $ sudo pip install prestans --upgrade If you need to run multiple versions of Prestans on a server, consider using Virtualenv. Warning: Prestans 2.0 is backwards incompatible. 1.x is still available for download, upgrading to 2.x will break your 1.x application. Alternatively you can download and build Prestans using distutils: $ tar -zxvf prestans-2.x.x.tgz $ cd prestans-2.x.x $ sudo 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 (unless of course you require a bleeding edge feature). • If you prefer to include Prestans as a Git submodule, ensure you use reference one of the tags. • If your server environment has hard limits on number of files, consider using zipimport. As a Git submodule: $ git submodule add https://github.com/anomaly/prestans.git ext/prestans When including Prestans manually ensure that your web server is able to locate the files. 1.1 Software Requirements The server side requires a WSGI compliant environment: • Python 2.7 • WSGI compliant server environment (Apache+ mod_wsgi, or Google AppEngine, etc). 3 Prestans Documentation, Release 2.0 • WebOb 1.2.3 (if you’re using PyPI this should be installed as a dependency, AppEngine already provides We- bOb) • Your choice of a persistent store might require you to install SQLAlchemy or AppEngine Datastore. Google Closure Library Extensions covers our client side Javascript library for Google Closure projects. We mostly test on latest releases of Ubuntu Server, and Google’s AppEngine. 1.2 Deployment notes The following are environment specific deployment gotchas. Things we’ve learnt the hard way. We’ll ensure to constantly keep updating this section as we find more, we also encourage you to keep a eye out on our mailing lists. 1.2.1 Apache + mod_wsgi Consider the following directory stucture, you might wish to checkout a bleeding edge Prestans into a source controlled directory (in this instance Git): +-- app +-- conf +-- static +-- ext +-- prestans +-- client +-- conf project.pth mod_wsgi’s WSGIPythonPath directive tells mod_wsgi to add any locations delclared in files with the .pth extension to the runtime Python path. This allows you to put Python modules in a directory e.g ext and distribute it with your project. 1.2.2 AppEngine Python projects under AppEngine use a YAML configuration file called app.yaml to specify versions of Python li- braries you project requires. Ensure that you have one of the following included in your app.yaml file. During development: libraries: - name: webob version: latest During deployment: libraries: - name: webob version: "1.2.3"