Developing RESTful Web APIs with Python, Flask and MongoDB

Slide 1

Slide 1 text

RESTful Web API With Python, Flask and Mongo Nicola Iarocci mercoledì 4 luglio 2012

Slide 2

Slide 2 text

Good Morning. mercoledì 4 luglio 2012

Slide 3

Slide 3 text

@nicolaiarocci mercoledì 4 luglio 2012

Slide 4

Slide 4 text

Full Disclosure mercoledì 4 luglio 2012

Slide 5

Slide 5 text

I’m a .NET guy 20 years in the Microsoft ecosystem Scary, Yes. mercoledì 4 luglio 2012

Slide 6

Slide 6 text

mercoledì 4 luglio 2012

Slide 7

Slide 7 text

Still with me? Great. mercoledì 4 luglio 2012

Slide 8

Slide 8 text

gestionaleamica.com invoicing & accounting mercoledì 4 luglio 2012

Slide 9

Slide 9 text

Your Typical Old School Desktop App... ... now going web & mobile mercoledì 4 luglio 2012

Slide 10

Slide 10 text

Enter Python Flask and Mongo mercoledì 4 luglio 2012

Slide 11

Slide 11 text

REST So What Is REST All About? mercoledì 4 luglio 2012

Slide 12

Slide 12 text

REST is not a standard mercoledì 4 luglio 2012

Slide 13

Slide 13 text

REST is not a protocol mercoledì 4 luglio 2012

Slide 14

Slide 14 text

REST is an architectural style for networked applications mercoledì 4 luglio 2012

Slide 15

Slide 15 text

REST defines a set of simple principles loosely followed by most API implementations mercoledì 4 luglio 2012

Slide 16

Slide 16 text

#1 resource the source of a specific information mercoledì 4 luglio 2012

Slide 17

Slide 17 text

A web page is not a resource rather, the representation of a resource mercoledì 4 luglio 2012

Slide 18

Slide 18 text

#2 global permanent identifier every resource is uniquely identified (think a HTTP URI) mercoledì 4 luglio 2012

Slide 19

Slide 19 text

#3 standard interface used to exchange representations of resources (think the HTTP protocol) mercoledì 4 luglio 2012

Slide 20

Slide 20 text

#4 set of constraints separation of concerns, stateless, cacheability, layered system, uniform interface... we’ll get to these later mercoledì 4 luglio 2012

Slide 21

Slide 21 text

The World Wide Web is built on REST and it is meant to be consumed by humans mercoledì 4 luglio 2012

Slide 22

Slide 22 text

RESTful Web APIs are built on REST and are meant to be consumed by machines mercoledì 4 luglio 2012

Slide 23

Slide 23 text

How I Explained REST to My Wife by Ryan Tomayko http://tomayko.com/writings/rest-to-my-wife Beginners Reading mercoledì 4 luglio 2012

Slide 24

Slide 24 text

Representational State Transfer (REST) by Roy Thomas Fielding http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm The Real Stuff mercoledì 4 luglio 2012

Slide 25

Slide 25 text

RESTful Web API Nuts & Bolts mercoledì 4 luglio 2012

Slide 26

Slide 26 text

The Tools or why I picked Flask and Mongo mercoledì 4 luglio 2012

Slide 27

Slide 27 text

Flask web development, one drop at a time mercoledì 4 luglio 2012

Slide 28

Slide 28 text

Simple & Elegant from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" if __name__ == "__main__": app.run(debug=True) mercoledì 4 luglio 2012

Slide 29

Slide 29 text

RESTful request dispacthing @app.route('/user/') def show_user_profile(username): return 'User %s' % username @app.route('/post/') def show_post(post_id): return 'Post %d' % post_id mercoledì 4 luglio 2012

Slide 30

Slide 30 text

from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" if __name__ == "__main__": app.run(debug=True) Built-in development server & debugger mercoledì 4 luglio 2012

Slide 31

Slide 31 text

from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" if __name__ == "__main__": app.run(debug=True) Explicit & passable application objects mercoledì 4 luglio 2012

Slide 32

Slide 32 text

from flask import Flask app = Flask(__name__) @app.route("/") def hello(): return "Hello World!" if __name__ == "__main__": app.run(debug=True) 100% WSGI Compliant e.g., response objects are WSGI applications themselves mercoledì 4 luglio 2012

Slide 33

Slide 33 text

Only 800 lines of source code Minimal Footprint mercoledì 4 luglio 2012

Slide 34

Slide 34 text

1500 lines of tests Heavily Tested mercoledì 4 luglio 2012

Slide 35

Slide 35 text

one day I will make good use of it Unittesting Support mercoledì 4 luglio 2012

Slide 36

Slide 36 text

we aim for flexibility Bring Your Own Batteries mercoledì 4 luglio 2012

Slide 37

Slide 37 text

No built-in ORM we want to be as close to the bare metal as possible mercoledì 4 luglio 2012

Slide 38

Slide 38 text

No form validation we don’t need no freaking form validation mercoledì 4 luglio 2012

Slide 39

Slide 39 text

Python offers great tools to manipulate JSON, we can tinker something ourselves No data validation mercoledì 4 luglio 2012

Slide 40

Slide 40 text

built on Werkzeug, Jinja2, WSGI Layered API mercoledì 4 luglio 2012

Slide 41

Slide 41 text

The Pocoo Team did Werkzeug, Jinja2, Sphinx, Pygments, and much more Built by the Pros mercoledì 4 luglio 2012

Slide 42

Slide 42 text

Over 200 pages, lots of examples and howtos Excellent Documentation mercoledì 4 luglio 2012

Slide 43

Slide 43 text

Widely adopted, extensions for everything Active Community mercoledì 4 luglio 2012

Slide 44

Slide 44 text

Kenneth Reitz, DjangoCon 2012 “Flask is a sharp tool for building sharp services” mercoledì 4 luglio 2012

Slide 45

Slide 45 text

MongoDB scalable, high-performance, open source NoSQL database mercoledì 4 luglio 2012

Slide 46

Slide 46 text

made NoSQL easy to grasp (even for a dumbhead like me) Similarity with RDBMS mercoledì 4 luglio 2012

Slide 47

Slide 47 text

Terminology RDBMS Mongo Database Database Table Collection Rows(s) JSON Document Index Index Join Embedding & Linking mercoledì 4 luglio 2012

Slide 48

Slide 48 text

true selling point for me JSON-style data store mercoledì 4 luglio 2012

Slide 49

Slide 49 text

JSON & RESTful API JSON accepted media type Client JSON (BSON) Mongo GET maybe we can push directly to client? mercoledì 4 luglio 2012

Slide 50

Slide 50 text

JSON & RESTful API JSON accepted media type Client JSON (BSON) Mongo JSON/dict maps to python dict API GET almost. mercoledì 4 luglio 2012

Slide 51

Slide 51 text

JSON & RESTful API JSON objects Client JSON (BSON) Mongo JSON/dict maps to python dict (validation layer) API POST also works when posting (adding) items to the database mercoledì 4 luglio 2012

Slide 52

Slide 52 text

Queries in MongoDB are represented as JSON-style objects What about Queries? // select * from things where x=3 and y="foo" db.things.find({x: 3, y: "foo”}); mercoledì 4 luglio 2012

Slide 53

Slide 53 text

JSON & RESTful API native Mongo query syntax Client JSON (BSON) Mongo (very) thin parsing & validation layer API FILTERING & SORTING ?where={x: 3, y: "foo”} mercoledì 4 luglio 2012

Slide 54

Slide 54 text

mapping to and from the database feels more natural JSON all along the pipeline mercoledì 4 luglio 2012

Slide 55

Slide 55 text

dynamic objects allow for a painless evolution of our schema (because yes, a schema exists at any point in time) Schema-less mercoledì 4 luglio 2012

Slide 56

Slide 56 text

Where we’re going we don’t need ORMs. ORM mercoledì 4 luglio 2012

Slide 57

Slide 57 text

official Python driver all we need to interact with the database PyMongo mercoledì 4 luglio 2012

Slide 58

Slide 58 text

Also in MongoDB • setup is a breeze • lightweight • fast inserts, updates and queries • excellent documentation • great support by 10gen • great community mercoledì 4 luglio 2012

Slide 59

Slide 59 text

The Little MongoDB Book by Karl Seguin http://openmymind.net/2011/3/28/The-Little-MongoDB-Book/ A Great Introduction To MongoDB mercoledì 4 luglio 2012

Slide 60

Slide 60 text

Il Piccolo Libro di MongoDB by Karl Seguin, traduzione di Nicola Iarocci http://nicolaiarocci.com/il-piccolo-libro-di-mongodb-edizione-italiana/ Shameless Plug mercoledì 4 luglio 2012

Slide 61

Slide 61 text

MongoDB Interactive Tutorial http://tutorial.mongly.com/tutorial/index mercoledì 4 luglio 2012

Slide 62

Slide 62 text

RESTful Web APIs are really just collection of resources accesible through to a uniform interface mercoledì 4 luglio 2012

Slide 63

Slide 63 text

#1 each resource is identified by a persistent identifier We need to properly implement Request Dispatching mercoledì 4 luglio 2012

Slide 64

Slide 64 text

Collections API’s entry point + plural nouns http://api.example.com/v1/contacts mercoledì 4 luglio 2012

Slide 65

Slide 65 text

Collections Flask URL dispatcher allows for variables @app.route('/') def collection(collection): if collection in DOMAIN.keys(): (...) abort(404) api.example.com/contacts api.example.com/invoices etc. mercoledì 4 luglio 2012

Slide 66

Slide 66 text

validation dictonary Collections Flask URL dispatcher allows for variables @app.route('/') def collection(collection): if collection in DOMAIN.keys(): (...) abort(404) mercoledì 4 luglio 2012

Slide 67

Slide 67 text

we don’t know this collection, return a 404 Collections Flask URL dispatcher allows for variables @app.route('/') def collection(collection): if collection in DOMAIN.keys(): (...) abort(404) mercoledì 4 luglio 2012

Slide 68

Slide 68 text

@app.route('/') def collection(collection): if collection in DOMAIN.keys(): (...) abort(404) regular expressions can be used to better narrow a variable part URL. However... RegEx by design, collection URLs are plural nouns mercoledì 4 luglio 2012

Slide 69

Slide 69 text

RegEx We need to build our own Custom Converter class RegexConverter(BaseConverter): def __init__(self, url_map, *items): super(RegexConverter, self).__init__(url_map) self.regex = items[0] app.url_map.converters['regex'] = RegexConverter subclass BaseConverter and pass the new converter to the url_map mercoledì 4 luglio 2012

Slide 70

Slide 70 text

And eventually by an alternative lookup value Document http://api.example.com/v1/contacts/CUST12345 Documents are identified by ObjectID http://api.example.com/v1/contacts/4f46445fc88e201858000000 mercoledì 4 luglio 2012

Slide 71

Slide 71 text

@app.route('//') @app.route('/' '/') def document(collection, lookup=None, object_id=None): (...) URL dispatcher handles multiple variables http://api.example.com/v1/contacts/CUST12345 Document mercoledì 4 luglio 2012

Slide 72

Slide 72 text

Document and of course it also handles multiple RegEx variables http://api.example.com/v1/contacts/4f46445fc88e201858000000 @app.route('//') @app.route('/' '/') def document(collection, lookup=None, object_id=None): (...) mercoledì 4 luglio 2012

Slide 73

Slide 73 text

Document Different URLs can be dispatched to the same function just by piling up @app.route decorators. @app.route('//') @app.route('/' '/') def document(collection, lookup=None, object_id=None): (...) mercoledì 4 luglio 2012

Slide 74

Slide 74 text

#2 representation of resources via media types JSON, XML or any other valid internet media type depends on the request and not the identifier mercoledì 4 luglio 2012

Slide 75

Slide 75 text

Accepted Media Types mapping supported media types to corresponding renderer functions mime_types = {'json_renderer': ('application/json',), 'xml_renderer': ('application/xml', 'text/xml', 'application/x-xml',)} JSON rendering function mercoledì 4 luglio 2012

Slide 76

Slide 76 text

Accepted Media Types mime_types = {'json_renderer': ('application/json',), 'xml_renderer': ('application/xml', 'text/xml', 'application/x-xml',)} corresponding JSON internet media type mapping supported media types to corresponding renderer functions mercoledì 4 luglio 2012

Slide 77

Slide 77 text

Accepted Media Types mime_types = {'json_renderer': ('application/json',), 'xml_renderer': ('application/xml', 'text/xml', 'application/x-xml',)} XML rendering function mapping supported media types to corresponding renderer functions mercoledì 4 luglio 2012

Slide 78

Slide 78 text

Accepted Media Types mime_types = {'json_renderer': ('application/json',), 'xml_renderer': ('application/xml', 'text/xml', 'application/x-xml',)} corresponding XML internet media types mapping supported media types to corresponding renderer functions mercoledì 4 luglio 2012

Slide 79

Slide 79 text

JSON Render datetimes and ObjectIDs call for further tinkering renderer function mapped to the appication/json media type class APIEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime.datetime): return date_to_str(obj) elif isinstance(obj, ObjectId): return str(obj) return json.JSONEncoder.default(self, obj) def json_renderer(**data): return json.dumps(data, cls=APIEncoder) mercoledì 4 luglio 2012

Slide 80

Slide 80 text

JSON Render datetimes and ObjectIDs call for further tinkering standard json encoding is not enough, we need a specialized JSONEncoder class APIEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime.datetime): return date_to_str(obj) elif isinstance(obj, ObjectId): return str(obj) return json.JSONEncoder.default(self, obj) def json_renderer(**data): return json.dumps(data, cls=APIEncoder) mercoledì 4 luglio 2012

Slide 81

Slide 81 text

class APIEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime.datetime): return date_to_str(obj) elif isinstance(obj, ObjectId): return str(obj) return json.JSONEncoder.default(self, obj) def json_renderer(**data): return json.dumps(data, cls=APIEncoder) JSON Render Python datetimes are encoded as RFC 1123 strings: “Wed, 06 Jun 2012 14:19:53 UTC” datetimes and ObjectIDs call for further tinkering mercoledì 4 luglio 2012

Slide 82

Slide 82 text

JSON Render class APIEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime.datetime): return date_to_str(obj) elif isinstance(obj, ObjectId): return str(obj) return json.JSONEncoder.default(self, obj) def json_renderer(**data): return json.dumps(data, cls=APIEncoder) Mongo ObjectId data types are encoded as strings: “4f46445fc88e201858000000” datetimes and ObjectIDs call for further tinkering mercoledì 4 luglio 2012

Slide 83

Slide 83 text

JSON Render we let json/simplejson handle the other data types class APIEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, datetime.datetime): return date_to_str(obj) elif isinstance(obj, ObjectId): return str(obj) return json.JSONEncoder.default(self, obj) def json_renderer(**data): return json.dumps(data, cls=APIEncoder) datetimes and ObjectIDs call for further tinkering mercoledì 4 luglio 2012

Slide 84

Slide 84 text

Rendering Render to JSON or XML and get WSGI response object best match between request Accept header and media types supported by the service def prep_response(dct, status=200): mime, render = get_best_mime() rendered = globals()[render](**dct) resp = make_response(rendered, status) resp.mimetype = mime return resp mercoledì 4 luglio 2012

Slide 85

Slide 85 text

Rendering Render to JSON or XML and get WSGI response object call the appropriate render function and retrieve the encoded JSON or XML def prep_response(dct, status=200): mime, render = get_best_mime() rendered = globals()[render](**dct) resp = make_response(rendered, status) resp.mimetype = mime return resp mercoledì 4 luglio 2012

Slide 86

Slide 86 text

Rendering Render to JSON or XML and get WSGI response object flask’s make_response() returns a WSGI response object wich we can use to attach headers def prep_response(dct, status=200): mime, render = get_best_mime() rendered = globals()[render](**dct) resp = make_response(rendered, status) resp.mimetype = mime return resp mercoledì 4 luglio 2012

Slide 87

Slide 87 text

Rendering Render to JSON or XML and get WSGI response object and finally, we set the appropriate mime type in the response header def prep_response(dct, status=200): mime, render = get_best_mime() rendered = globals()[render](**dct) resp = make_response(rendered, status) resp.mimetype = mime return resp mercoledì 4 luglio 2012

Slide 88

Slide 88 text

Flask-MimeRender “Python module for RESTful resource representation using MIME Media-Types and the Flask Microframework” !"!#"$%&'((#)('%*+,",-.-$/-. mercoledì 4 luglio 2012

Slide 89

Slide 89 text

Flask-MimeRender Render Functions render_json = jsonify render_xml = lambda message: '%s' % message render_txt = lambda message: message render_html = lambda message: '%s' % \ message mercoledì 4 luglio 2012

Slide 90

Slide 90 text

Flask-MimeRender then you just decorate your end-point function @app.route('/') @mimerender( default = 'html', html = render_html, xml = render_xml, json = render_json, txt = render_txt ) def index(): if request.method == 'GET': return {'message': 'Hello, World!'} mercoledì 4 luglio 2012

Slide 91

Slide 91 text

Flask-MimeRender Requests $ curl -H "Accept: application/html" example.com/ Hello, World! $ curl -H "Accept: application/xml" example.com/ Hello, World! $ curl -H "Accept: application/json" example.com/ {'message':'Hello, World!'} $ curl -H "Accept: text/plain" example.com/ Hello, World! mercoledì 4 luglio 2012

Slide 92

Slide 92 text

“GET, POST, PUT, DELETE and all that mess” #3 resource manipulation through HTTP verbs mercoledì 4 luglio 2012

Slide 93

Slide 93 text

HTTP Methods Verbs are handled along with URL routing @app.route('/', methods=['GET', 'POST']) def collection(collection): if collection in DOMAIN.keys(): if request.method == 'GET': return get_collection(collection) elif request.method == 'POST': return post(collection) abort(404) accepted HTTP verbs a PUT will throw a 405 Command Not Allowed mercoledì 4 luglio 2012

Slide 94

Slide 94 text

@app.route('/', methods=['GET', 'POST']) def collection(collection): if collection in DOMAIN.keys(): if request.method == 'GET': return get_collection(collection) elif request.method == 'POST': return post(collection) abort(404) HTTP Methods Verbs are handled along with URL routing the global request object provides access to clients’ request headers mercoledì 4 luglio 2012

Slide 95

Slide 95 text

@app.route('/', methods=['GET', 'POST']) def collection(collection): if collection in DOMAIN.keys(): if request.method == 'GET': return get_collection(collection) elif request.method == 'POST': return post(collection) abort(404) HTTP Methods Verbs are handled along with URL routing we respond to a GET request for a ‘collection’ resource mercoledì 4 luglio 2012

Slide 96

Slide 96 text

@app.route('/', methods=['GET', 'POST']) def collection(collection): if collection in DOMAIN.keys(): if request.method == 'GET': return get_collection(collection) elif request.method == 'POST': return post(collection) abort(404) HTTP Methods Verbs are handled along with URL routing and here we respond to a POST request. Handling HTTP methods is easy! mercoledì 4 luglio 2012

Slide 97

Slide 97 text

CRUD via REST Acttion HTTP Verb Context Get GET Collection/ Document Create POST Collection Update PATCH* Document Delete DELETE Document * WTF? mercoledì 4 luglio 2012

Slide 98

Slide 98 text

Retrieve Multiple Documents (accepting Queries) http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} GET mercoledì 4 luglio 2012

Slide 99

Slide 99 text

Collection GET def get_collection(collection): where = request.args.get('where') if where: args['spec'] = json.loads(where, object_hook=datetime_parser) (...) response = {} documents = [] cursor = db(collection).find(**args) for document in cursor: documents.append(document) response[collection] = documents return prep_response(response) request.args returns the original URI’s query definition, in our example: where = {“age”: {“$gt”: 20}} http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} mercoledì 4 luglio 2012

Slide 100

Slide 100 text

Collection GET def get_collection(collection): where = request.args.get('where') if where: args['spec'] = json.loads(where, object_hook=datetime_parser) (...) response = {} documents = [] cursor = db(collection).find(**args) for document in cursor: documents.append(document) response[collection] = documents return prep_response(response) as the query already comes in as a Mongo expression: {“age”: {“$gt”: 20}} we simply convert it to JSON. http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} mercoledì 4 luglio 2012

Slide 101

Slide 101 text

Collection GET def get_collection(collection): where = request.args.get('where') if where: args['spec'] = json.loads(where, object_hook=datetime_parser) (...) response = {} documents = [] cursor = db(collection).find(**args) for document in cursor: documents.append(document) response[collection] = documents return prep_response(response) String-to-datetime conversion is obtained via the object_hook mechanism http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} mercoledì 4 luglio 2012

Slide 102

Slide 102 text

Collection GET def get_collection(collection): where = request.args.get('where') if where: args['spec'] = json.loads(where, object_hook=datetime_parser) (...) response = {} documents = [] cursor = db(collection).find(**args) for document in cursor: documents.append(document) response[collection] = documents return prep_response(response) find() accepts a python dict as query expression, and returns a cursor we can iterate http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} mercoledì 4 luglio 2012

Slide 103

Slide 103 text

Collection GET def get_collection(collection): where = request.args.get('where') if where: args['spec'] = json.loads(where, object_hook=datetime_parser) (...) response = {} documents = [] cursor = db(collection).find(**args) for document in cursor: documents.append(document) response[collection] = documents return prep_response(response) finally, we encode the response dict with the requested MIME media-type http://api.example.com/v1/contacts?where={“age”: {“$gt”: 20}} mercoledì 4 luglio 2012

Slide 104

Slide 104 text

On encoding JSON dates Interlude mercoledì 4 luglio 2012

Slide 105

Slide 105 text

On encoding JSON dates • We don’t want to force metadata into JSON representation: (“updated”: “$date: Thu 1, ..”) • Likewise, epochs are not an option • We are aiming for a broad solution not relying on the knoweldge of the current domain mercoledì 4 luglio 2012

Slide 106

Slide 106 text

Because, you know the guy behind Redis mercoledì 4 luglio 2012

Slide 107

Slide 107 text

Parsing JSON dates object_hook is usually used to deserialize JSON to classes (rings a ORM bell?) >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 108

Slide 108 text

Parsing JSON dates the resulting dct now has datetime values instead of string representations of dates >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 109

Slide 109 text

Parsing JSON dates the function receives a dict representing the decoded JSON >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 110

Slide 110 text

Parsing JSON dates strings matching the RegEx (which probably should be better defined)... >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 111

Slide 111 text

Parsing JSON dates ...are converted to datetime values >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 112

Slide 112 text

Parsing JSON dates if conversion fails we assume that we are dealing a normal, legit string >>> source = '{"updated": "Thu, 1 Mar 2012 10:00:49 UTC"}' >>> dct = json.loads(source, object_hook=datetime_parser) >>> dct {u'updated': datetime.datetime(2012, 3, 1, 10, 0, 49)} def datetime_parser(dct): for k, v in dct.items(): if isinstance(v, basestring) and re.search("\ UTC", v): try: dct[k] = datetime.datetime.strptime(v, DATE_FORMAT) except: pass return dct this is what I came out with mercoledì 4 luglio 2012

Slide 113

Slide 113 text

Editing a Resource PATCH mercoledì 4 luglio 2012

Slide 114

Slide 114 text

Why not PUT? • PUT means resource creation or replacement at a given URL • PUT does not allow for partial updates of a resource • 99% of the time we are updating just one or two fields • We don’t want to send complete representations of the document we are updating • Mongo allows for atomic updates and we want to take advantage of that mercoledì 4 luglio 2012

Slide 115

Slide 115 text

‘atomic’ PUT updates are ok when each field is itself a resource http://api.example.com/v1/contacts//address mercoledì 4 luglio 2012

Slide 116

Slide 116 text

Enter PATCH “This specification defines the new method, PATCH, which is used to apply partial modifications to a resource.” RFC5789 mercoledì 4 luglio 2012

Slide 117

Slide 117 text

PATCH • send a “patch document” with just the changes to be applied to the document • saves bandwidth and reduces traffic • it’s been around since 1995 • it is a RFC Proposed Standard • Widely adopted (will replace PUT in Rails 4.0) • clients not supporting it can fallback to POST with ‘X-HTTP-Method-Override: PATCH’ header tag mercoledì 4 luglio 2012

Slide 118

Slide 118 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) request.form returns a dict with request form data. mercoledì 4 luglio 2012

Slide 119

Slide 119 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) we aren’t going to accept more than one document here mercoledì 4 luglio 2012

Slide 120

Slide 120 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) retrieve the original document ID, will be used by the update command mercoledì 4 luglio 2012

Slide 121

Slide 121 text

Slide 122

Slide 122 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) add validation results to the response dictionary mercoledì 4 luglio 2012

Slide 123

Slide 123 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) $set accepts a dict with the updates for the db eg: {“active”: False}. mercoledì 4 luglio 2012

Slide 124

Slide 124 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) mongo update() method commits updates to the database. Updates are atomic. mercoledì 4 luglio 2012

Slide 125

Slide 125 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) udpate() takes the unique Id of the document andthe update expression ($set) mercoledì 4 luglio 2012

Slide 126

Slide 126 text

PATCHing def patch_document(collection, original): docs = parse_request(request.form) if len(docs) > 1: abort(400) key, value = docs.popitem() response_item = {} object_id = original[ID_FIELD] # Validation validate(value, collection, object_id) response_item['validation'] = value['validation'] if value['validation']['response'] != VALIDATION_ERROR: # Perform the update updates = {"$set": value['doc']} db(collection).update({"_Id": ObjectId(object_id)}, updates) response_item[ID_FIELD] = object_id return prep_response(response_item) as always, our response dictionary is returned with proper encding mercoledì 4 luglio 2012

Slide 127

Slide 127 text

Creating Resources POST mercoledì 4 luglio 2012

Slide 128

Slide 128 text

POSTing we accept multiple documents (remember, we are at collection level here) def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 129

Slide 129 text

def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} POSTing we loop through the documents to be inserted mercoledì 4 luglio 2012

Slide 130

Slide 130 text

POSTing perform validation on the document def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 131

Slide 131 text

POSTing push document and get its ObjectId back from Mongo. like other CRUD operations, inserting is trivial in mongo. def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 132

Slide 132 text

POSTing a direct link to the resource we just created is added to the response def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 133

Slide 133 text

POSTing validation result is always returned to the client, even if the doc has not been inserted def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 134

Slide 134 text

POSTing standard response enconding applied def post(collection): docs = parse_request(request.form) response = {} for key, item in docs.items(): response_item = {} validate(item, collection) if item['validation']['response'] != VALIDATION_ERROR: document = item['doc'] response_item[ID_FIELD] = db(collection).insert(document) response_item['link'] = get_document_link(collection, response_item[ID_FIELD]) response_item['validation'] = item['validation'] response[key] = response_item return {'response': response} mercoledì 4 luglio 2012

Slide 135

Slide 135 text

Data Validation We still need to validate incoming data mercoledì 4 luglio 2012

Slide 136

Slide 136 text

Data Validation DOMAIN = {} DOMAIN['contacts'] = { 'secondary_id': 'name', 'fields': { 'name': { 'data_type': 'string', 'required': True, 'unique': True, 'max_length': 120, 'min_length': 1 }, DOMAIN is a Python dict containing our validation rules and schema structure mercoledì 4 luglio 2012

Slide 137

Slide 137 text

Data Validation every resource (collection) maintained by the API has a key in DOMAIN DOMAIN = {} DOMAIN['contacts'] = { 'secondary_id': 'name', 'fields': { 'name': { 'data_type': 'string', 'required': True, 'unique': True, 'max_length': 120, 'min_length': 1 }, mercoledì 4 luglio 2012

Slide 138

Slide 138 text

Data Validation if the resource allows for a secondary lookup field, we define it here DOMAIN = {} DOMAIN['contacts'] = { 'secondary_id': 'name', 'fields': { 'name': { 'data_type': 'string', 'required': True, 'unique': True, 'max_length': 120, 'min_length': 1 }, mercoledì 4 luglio 2012

Slide 139

Slide 139 text

Data Validation known fields go in the fields dict DOMAIN = {} DOMAIN['contacts'] = { 'secondary_id': 'name', 'fields': { 'name': { 'data_type': 'string', 'required': True, 'unique': True, 'max_length': 120, 'min_length': 1 }, mercoledì 4 luglio 2012

Slide 140

Slide 140 text

Data Validation validation rules for ‘name’ field. data_type is mostly needed to process datetimes and currency values DOMAIN = {} DOMAIN['contacts'] = { 'secondary_id': 'name', 'fields': { 'name': { 'data_type': 'string', 'required': True, 'unique': True, 'max_length': 120, 'min_length': 1 }, mercoledì 4 luglio 2012

Slide 141

Slide 141 text

Data Validation we can define custom validation functions when the need arises (...) 'iban': { 'data_type': 'string', 'custom_validation': { 'module': 'customvalidation', 'function': 'validate_iban' } } (...) mercoledì 4 luglio 2012

Slide 142

Slide 142 text

Data Validation or we can define our own custom data types... (...) 'contact_type': { 'data_type': 'array', 'allowed_values': [ 'client', 'agent', 'supplier', 'area manager', 'vector' ] } (...) mercoledì 4 luglio 2012

Slide 143

Slide 143 text

Data Validation ... like the array, which allows us to define a list of accepted values for the field (...) 'contact_type': { 'data_type': 'array', 'allowed_values': [ 'client', 'agent', 'supplier', 'area manager', 'vector' ] } (...) mercoledì 4 luglio 2012

Slide 144

Slide 144 text

I will spare you the validation function It’s pretty simple really mercoledì 4 luglio 2012

Slide 145

Slide 145 text

Hey but! You’re building your own ORM! Just a thin validation layer on which I have total control AKA So What? mercoledì 4 luglio 2012

Slide 146

Slide 146 text

#4 Caching and concurrency control resource representation describes how when and if it can be used, discarded or re-fetched mercoledì 4 luglio 2012

Slide 147

Slide 147 text

Driving conditional requests Servers use Last-Modified and ETag response headers to drive conditional requests mercoledì 4 luglio 2012

Slide 148

Slide 148 text

Last-Modified Generally considered a weak validator since it has a one-second resolution “Wed, 06 Jun 2012 14:19:53 UTC” mercoledì 4 luglio 2012

Slide 149

Slide 149 text

ETag Entity Tag is a strong validator since its value can be changed every time the server modifies the representation 7a9f477cde424cf93a7db20b69e05f7b680b7f08 mercoledì 4 luglio 2012

Slide 150

Slide 150 text

On ETags • Clients should be able to use ETag to compare representations of a resouce • An ETag is supposed to be like an object’s hash code. • Actually, some web frameworks and a lot of implementations do just that • ETag computed on an entire representation of the resource may become a performance bottleneck mercoledì 4 luglio 2012

Slide 151

Slide 151 text

Last-Modified or ETag? You can use either or both. Consider the types of client consuming your service. Hint: use both. mercoledì 4 luglio 2012

Slide 152

Slide 152 text

Validating cached representations Clients use If-Modified-Since and If-None-Match in request headers for validating cached representations mercoledì 4 luglio 2012

Slide 153

Slide 153 text

If-Mod-Since & ETag def get_document(collection, object_id=None, lookup=None): response = {} document = find_document(collection, object_id, lookup) if document: etag = get_etag(document) header_etag = request.headers.get('If-None-Match') if header_etag and header_etag == etag: return prep_response(dict(), status=304) if_modified_since = request.headers.get('If-Modified-Since') if if_modified_since: last_modified = document[LAST_UPDATED] if last_modified <= if_modified_since: return prep_response(dict(), status=304) response[collection.rstrip('s')] = document return prep_response(response, last_modified, etag) abort(404) retrieve the document from the database mercoledì 4 luglio 2012

Slide 154

Slide 154 text

If-Mod-Since & ETag def get_document(collection, object_id=None, lookup=None): response = {} document = find_document(collection, object_id, lookup) if document: etag = get_etag(document) header_etag = request.headers.get('If-None-Match') if header_etag and header_etag == etag: return prep_response(dict(), status=304) if_modified_since = request.headers.get('If-Modified-Since') if if_modified_since: last_modified = document[LAST_UPDATED] if last_modified <= if_modified_since: return prep_response(dict(), status=304) response[collection.rstrip('s')] = document return prep_response(response, last_modified, etag) abort(404) compute ETag for the current representation. We test ETag first, as it is a stronger validator mercoledì 4 luglio 2012

Slide 155

Slide 155 text

If-Mod-Since & ETag def get_document(collection, object_id=None, lookup=None): response = {} document = find_document(collection, object_id, lookup) if document: etag = get_etag(document) header_etag = request.headers.get('If-None-Match') if header_etag and header_etag == etag: return prep_response(dict(), status=304) if_modified_since = request.headers.get('If-Modified-Since') if if_modified_since: last_modified = document[LAST_UPDATED] if last_modified <= if_modified_since: return prep_response(dict(), status=304) response[collection.rstrip('s')] = document return prep_response(response, last_modified, etag) abort(404) retrieve If-None-Match ETag from request header mercoledì 4 luglio 2012

Slide 156

Slide 156 text

If-Mod-Since & ETag def get_document(collection, object_id=None, lookup=None): response = {} document = find_document(collection, object_id, lookup) if document: etag = get_etag(document) header_etag = request.headers.get('If-None-Match') if header_etag and header_etag == etag: return prep_response(dict(), status=304) if_modified_since = request.headers.get('If-Modified-Since') if if_modified_since: last_modified = document[LAST_UPDATED] if last_modified <= if_modified_since: return prep_response(dict(), status=304) response[collection.rstrip('s')] = document return prep_response(response, last_modified, etag) abort(404) if client and server representations match, return a 304 Not Modified mercoledì 4 luglio 2012

Slide 157

Slide 157 text

If-Mod-Since & ETag def get_document(collection, object_id=None, lookup=None): response = {} document = find_document(collection, object_id, lookup) if document: etag = get_etag(document) header_etag = request.headers.get('If-None-Match') if header_etag and header_etag == etag: return prep_response(dict(), status=304) if_modified_since = request.headers.get('If-Modified-Since') if if_modified_since: last_modified = document[LAST_UPDATED] if last_modified <= if_modified_since: return prep_response(dict(), status=304) response[collection.rstrip('s')] = document return prep_response(response, last_modified, etag) abort(404) likewise, if the resource has not been modified since If-Modifed-Since, return 304 Not Modified mercoledì 4 luglio 2012

Slide 158

Slide 158 text

Concurrency control Clients use If-Unmodified-Since and If-Match in request headers as preconditions for concurrency control mercoledì 4 luglio 2012

Slide 159

Slide 159 text

def edit_document(collection, object_id, method): document = find_document(collection, object_id) if document: header_etag = request.headers.get('If-Match') if header_etag is None: return prep_response('If-Match missing from request header', status=403) if header_etag != get_etag(document[LAST_UPDATED]): # Precondition failed abort(412) else: if method in ('PATCH', 'POST'): return patch_document(collection, document) elif method == 'DELETE': return delete_document(collection, object_id) else: abort(404) Concurrency control Create/Update/Delete are controlled by ETag retrieve client’s If-Match ETag from the request header mercoledì 4 luglio 2012

Slide 160

Slide 160 text

Concurrency control Create/Update/Delete are controlled by ETag editing is forbidden if ETag is not provided def edit_document(collection, object_id, method): document = find_document(collection, object_id) if document: header_etag = request.headers.get('If-Match') if header_etag is None: return prep_response('If-Match missing from request header', status=403) if header_etag != get_etag(document[LAST_UPDATED]): # Precondition failed abort(412) else: if method in ('PATCH', 'POST'): return patch_document(collection, document) elif method == 'DELETE': return delete_document(collection, object_id) else: abort(404) mercoledì 4 luglio 2012

Slide 161

Slide 161 text

Concurrency control Create/Update/Delete are controlled by ETag def edit_document(collection, object_id, method): document = find_document(collection, object_id) if document: header_etag = request.headers.get('If-Match') if header_etag is None: return prep_response('If-Match missing from request header', status=403) if header_etag != get_etag(document[LAST_UPDATED]): # Precondition failed abort(412) else: if method in ('PATCH', 'POST'): return patch_document(collection, document) elif method == 'DELETE': return delete_document(collection, object_id) else: abort(404) client and server representations don’t match. Precondition failed. mercoledì 4 luglio 2012

Slide 162

Slide 162 text

Concurrency control Create/Update/Delete are controlled by ETag def edit_document(collection, object_id, method): document = find_document(collection, object_id) if document: header_etag = request.headers.get('If-Match') if header_etag is None: return prep_response('If-Match missing from request header', status=403) if header_etag != get_etag(document[LAST_UPDATED]): # Precondition failed abort(412) else: if method in ('PATCH', 'POST'): return patch_document(collection, document) elif method == 'DELETE': return delete_document(collection, object_id) else: abort(404) client and server representation match, go ahead with the edit mercoledì 4 luglio 2012

Slide 163

Slide 163 text

Sending cache & concurrency directives back to clients mercoledì 4 luglio 2012

Slide 164

Slide 164 text

Cache & Concurrency def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp encodes ‘dct’ according to client’s accepted MIME Data-Type (click here see that slide) mercoledì 4 luglio 2012

Slide 165

Slide 165 text

Cache & Concurrency Cache-Control, a directive for HTTP/1.1 clients (and later) -RFC2616 def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp mercoledì 4 luglio 2012

Slide 166

Slide 166 text

Cache & Concurrency Expires, a directive for HTTP/1.0 clients def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp mercoledì 4 luglio 2012

Slide 167

Slide 167 text

Cache & Concurrency ETag. Notice that we don’t compute it on the rendered representation, this is by design. def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp mercoledì 4 luglio 2012

Slide 168

Slide 168 text

Cache & Concurrency And finally, we add the Last-Modified header tag. def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp mercoledì 4 luglio 2012

Slide 169

Slide 169 text

Cache & Concurrency the response object is now complete and ready to be returned to the client def prep_response(dct, last_modified=None, etag=None, status=200): (...) resp.headers.add('Cache-Control', 'max-age=%s,must-revalidate' & 30) resp.expires = time.time() + 30 if etag: resp.headers.add('ETag', etag) if last_modified: resp.headers.add('Last-Modified', date_to_str(last_modified)) return resp mercoledì 4 luglio 2012

Slide 170

Slide 170 text

#5 HATEOAS “Hypertext As The Engine Of Application State” that’s one long ass acronym mercoledì 4 luglio 2012

Slide 171

Slide 171 text

HATEOAS in a Nutshell • clients interact entirely through hypermedia provided dynamically by the server • clients need no prior knowledge about how to interact with the server • clients access an application through a single well known URL (the entry point) • All future actions the clients may take are discovered within resource representations returned from the server mercoledì 4 luglio 2012

Slide 172

Slide 172 text

It’s all about Links resource representation includes links to related resources mercoledì 4 luglio 2012

Slide 173

Slide 173 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation every resource representation provides a links section with navigational info for clients mercoledì 4 luglio 2012

Slide 174

Slide 174 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation the rel attribute provides the relationship between the linked resource and the one currently represented mercoledì 4 luglio 2012

Slide 175

Slide 175 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation the title attribute provides a tag (or description) for the linked resource. Could be used as a caption for a client button. mercoledì 4 luglio 2012

Slide 176

Slide 176 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation the href attribute provides and absolute path to the resource (the “permanent identifier” per REST def.) mercoledì 4 luglio 2012

Slide 177

Slide 177 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation every resource listed exposes its own link, which will allow the client to perform PATCH, DELETE etc. on the resource mercoledì 4 luglio 2012

Slide 178

Slide 178 text

{ "links":[ "", "", "" ], "contacts":[ { "updated":"Wed, 06 Jun 2012 14:19:53 UTC", "name":"Jon Doe", "age": 27, "etag":"7a9f477cde424cf93a7db20b69e05f7b680b7f08", "link":"", "_id":"4f46445fc88e201858000000", }, ] } Collection Representation while we are here, notice how every resource also exposes its own etag, last-modified date. mercoledì 4 luglio 2012

Slide 179

Slide 179 text

HATEOAS The API entry point (the homepage) the API homepage responds to GET requests and provides links to its top level resources to the clients @app.route('/', methods=['GET']) def home(): response = {} links = [] for collection in DOMAIN.keys(): links.append("" % {'name': collection, 'collectionURI': collection_URI(collection)}) response['links'] = links return response mercoledì 4 luglio 2012

Slide 180

Slide 180 text

HATEOAS The API entry point (the homepage) for every collection of resources... @app.route('/', methods=['GET']) def home(): response = {} links = [] for collection in DOMAIN.keys(): links.append("" % {'name': collection, 'collectionURI': collection_URI(collection)}) response['links'] = links return response mercoledì 4 luglio 2012

Slide 181

Slide 181 text

HATEOAS The API entry point (the homepage) ... provide relation, title and link, or the persistent identifier @app.route('/', methods=['GET']) def home(): response = {} links = [] for collection in DOMAIN.keys(): links.append("" % {'name': collection, 'collectionURI': collection_URI(collection)}) response['links'] = links return response mercoledì 4 luglio 2012

Slide 182

Slide 182 text

Wanna see it running? Hopefully it won’t explode right into my face mercoledì 4 luglio 2012

Slide 183

Slide 183 text

Only complaint I have with Flask so far... Most recent HTTP methods not supported mercoledì 4 luglio 2012

Slide 184

Slide 184 text

508 NOT MY FAULT Not supported yet mercoledì 4 luglio 2012

Slide 185

Slide 185 text

208 WORKS FOR ME Not supported yet mercoledì 4 luglio 2012

Slide 186

Slide 186 text

Just kidding! it isn’t even my joke! mercoledì 4 luglio 2012

Slide 187

Slide 187 text

Introducing My next open source project

Slide 188

Slide 188 text

Eve Effortlessly build and deploy a fully featured proprietary API

Slide 189

Slide 189 text

Eve is Open Source and brings at your fingertips all the features mentioned in this talk

Slide 190

Slide 190 text

Check it out at https://github.com/nicolaiarocci/eve

Slide 191

Slide 191 text

Web Resources • Richardson Maturity Model: steps toward the glory of REST by Richard Flowers • RESTful Service Best Practices by Todd Fredrich • What Exactly is RESTful Programming? StackOverflow (lots of resources) • API Anti-Patterns: How to Avoid Common REST Mistakes by Tomas Vitvar mercoledì 4 luglio 2012