RESTFUL SERVICES MADE EASY: THE EVE REST API FRAMEWORK - Nicola Iarocci - Codemotion Rome 2017

RESTful Web Services
for human beings
Nicola Iarocci
ROME 24-25 MARCH 2017

Nicola Iarocci
Co-Founder @ CIR2000
Lead Developer @ gestionaleamica.com
Microsoft MVP, MongoDB Master
Open Source Author
CoderDojo Ravenna (Italy)
@nicolaiarocci / nicolaiarocci.com

REST API FOR HUMANSeveREST WEB API
eve

RUN.PY
from eve import Eve
app = Eve()
app.run()

SETTINGS.PY
# just a couple API endpoints with no
# custom options and validation rules
DOMAIN = {
'people': {}
'books': {}
}

LAUNCH THE API
$ python run.py
* Running on http://127.0.0.1:5000/

TEST YOUR API
$ curl -i http://localhost:5000/
{
"_items": [],
"_links": {
"self": {
"href": "127.0.0.1:5000/people",
"title": "people" },
"parent": {
"href": "127.0.0.1:5000",
"title": "home"}
}
}

{
"_items": [],
"_links": {
"self": {
"href": "127.0.0.1:5000/people",
"parent": {
"href": "127.0.0.1:5000",
"title": "home"}
}
}
HATEOAS AT WORK HERE
TEST YOUR API

{
"_items": [],
"_links": {
"self": {
"href": "127.0.0.1:5000/people",
"parent": {
"href": "127.0.0.1:5000",
"title": "home"}
}
}
TEST YOUR API
CLIENTS CAN EXPLORE
THE API PROGRAMMATICALLY

{
"_items": [],
"_links": {
"self": {
"href": "127.0.0.1:5000/people",
"parent": {
"href": "127.0.0.1:5000",
"title": "home"}
}
}
TEST YOUR API
AND EVENTUALLY
FILL THEIR UI

{
"_items": [],
"_links": {
"self": {
"href": "127.0.0.1:5000/people",
"parent": {
"href": "127.0.0.1:5000",
"title": "home"}
}
}
EMTPY AS WE DIDN’T
CONNECT A DATASOURCE
TEST YOUR API

SETTINGS.PY
# connect to mongo
MONGO_HOST = 'localhost'
MONGO_PORT = 27017
MONGO_USERNAME = 'user'
MONGO_PASSWORD = 'user'
MONGO_DBNAME = 'apitest'

# add fields and validation rules for 'people' endpoint
DOMAIN['people']['schema'] = {
'name': {
'type': 'string',
'maxlength': 50,
'unique': True}
'email': {
'type': 'string',
'regex': '^S+@S+$'},
'location': {
'type': 'dict',
'schema': {
'address': {'type': 'string'},
'city': {'type': 'string'}}},
'born': {'type': 'datetime'}}
USE BETTER REGEX IN PRODUCTION
SETTINGS.PY

SETTINGS.PY
# enable writes. default is ['GET']
# /people
RESOURCE_METHODS = ['GET','POST']
# /people/<id>
ITEM_METHODS = ['GET','PATCH','PUT','DELETE']

# /people
# /people/<id>
SETTINGS.PY
ADD/CREATE ONE OR MORE
ITEMS

# /people
# /people/<id>
SETTINGS.PY
UPDATE
DOCUMENT

# /people
# /people/<id>
SETTINGS.PY
REPLACE
DOCUMENT

# /people
# /people/<id>
SETTINGS.PY
YOU GUESSED IT

SETTINGS.PY
# a few additional configuration options
DOMAIN['people'].update(
{
'item_title': 'person',
'cache_control': 'max-age=10,must-revalidate',
'cache_expires': 10,
'additional_lookup': {
'url': 'regex("[w]+")',
'field': 'name'
}
)

MONGO FILTERS
?where={“lastname”: “Doe”}

PYTHON FILTERS
?where=lastname==“Doe”

SORTING
?sort=-total
SORT BY ‘TOTAL’, DESCENDING

SORTING
?sort=[(“total”: -1)]
SAME, MONGODB-STYLE
DEMO

PAGINATION
?max_results=20&page=2
MAX 20 RESULTS PER PAGE;
GIVE ME PAGE 2

PROJECTIONS
?projection={"avatar": 0}
RETURN ALL FIELDS
BUT ‘AVATAR’

PROJECTIONS
?projection={"lastname": 1}
ONLY RETURN ‘LASTNAME’

EMBEDDED RESOURCES
?embedded={"author": 1}
DEMO

NOT EMBEDDED
$ curl -i <url>
HTTP/1.1 200 OK
{
"title": "Book Title",
"description": "book description",
"author": "52da465a5610320002660f94"
}
RAW FOREIGN
KEY

EMBEDDED
$ curl -i <url>?embedded={"author": 1}
HTTP/1.1 200 OK
{
"author": {
"firstname": "Mark",
"lastname": "Green",
}
}
REQUEST AN
EMBEDDED AUTHOR

EMBEDDED
$ curl -i <url>?embedded={"author": 1}
HTTP/1.1 200 OK
{
"author": {
}
}
EMBEDDED
DOCUMENT

JSON AND XML
SERIALIZATION FOR ALL RESPONSES
DEMO

APPLICATION/JSON
[
{
"born": "Sat, 23 Feb 1985 12:00:00 GMT",
"role": ["copy", "author"],
"location": {"city": "New York", "address": "4925 Lacross Road"},
"_id": "50bf198338345b1c604faf31",
"_updated": "Wed, 05 Dec 2012 09:53:07 GMT",
"_created": "Wed, 05 Dec 2012 09:53:07 GMT",
"_etag": "ec5e8200b8fa0596afe9ca71a87f23e71ca30e2d",
},
{
"firstname": "John",
...
},
]

[
{
"born": "Sat, 23 Feb 1985 12:00:00 GMT",
"role": ["copy", "author"],
"location": {"city": "New York", "address": "4925 Lacross Road"},
"_id": "50bf198338345b1c604faf31",
"_updated": "Wed, 05 Dec 2012 09:53:07 GMT",
"_created": "Wed, 05 Dec 2012 09:53:07 GMT",
"_etag": "ec5e8200b8fa0596afe9ca71a87f23e71ca30e2d",
},
{
"firstname": "John",
...
},
]
APPLICATION/JSON
METAFIELDS ARE
CUSTOMIZABLE

APPLICATION/XML
<resource href="localhost:5000/people" title="people">
<resource href="localhost:5000/people/<id>" title="person">
<lastname>Green</lastname>
<firstname>Mark</firstname>
<born>Wed, 05 Dec 2012 09:53:07 GMT</born>
<role>author</role>
<role>copy</role>
<location>
<address>4925 Lacross Road</address>
<city>New York</city>
</location>
<_id>50bf198338345b1c604faf31</_id>
<created>Wed, 05 Dec 2012 09:53:07 GMT</created>
<updated>Sat, 18 Jan 2014 09:16:10 GMT</updated>
<etag>ec5e8200b8fa0596afe9ca71a87f23e71ca30e2d</etag>
</resource>
...
<resource>

HATEOAS
HYPERMEDIA AS THE ENGINE OF APPLICATION STATE

HATEOAS
{
"_links": {
"self": {
"href": "/people",
"parent": {
"href": "/",
"title": "home"},
"next": {
"href": "/people?page=2",
"title": "next page"},
"last": {
"href": "/people?page=10",
"title": "last page"}
}
}

DOCUMENT VERSIONS
?version=3
?version=all
?version=diffs

FILE STORAGE
FILES ARE STORED IN GRIDFS BY DEFAULT

FILE STORAGE / SETTINGS
accounts = {
"name": {"type": "string"},
"pic": {"type": "media"},
}

FILE UPLOAD
$ curl F "name=doe" -F "pic=@profile.jpg" <url>
HTTP/1.1 200 OK
$ curl -i <url>
HTTP/1.1 200 OK
{
"name": "john",
"pic": "/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAâ€¦"
}
MULTIPART/DATA-FORM
POST

FILE UPLOAD
$ curl F "name=doe" -F "pic=@profile.jpg" <url>
HTTP/1.1 200 OK
$ curl -i <url>
HTTP/1.1 200 OK
{
"name": "john",
"pic": "/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAA…"
}
FILES RETURNED AS BASE64 STRINGS

FILE STORAGE (WITH META)
$ curl -i <url>
HTTP/1.1 200 OK
{
"name": "john",
"pic": {
"file": "/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAA",
"content_type": "image/jpeg",
"name": "profile.jpg",
"length": 8129
}
}
EXTENDED_MEDIA_INFO: [‘content_type, ‘name’, ‘length’]

FILE STORAGE (DEDICATED ENDPOINT)
$ curl -i <url>
HTTP/1.1 200 OK
{
"name": "john",
"pic": "/media/profile.jpg"
}
} RETURN_MEDIA_AS_URL = True
MEDIA_ENDPOINT = "media"

RATE LIMITING / SETTINGS
# Set rate limit on GET requests:
# 1 requests 1 minute window (per client)
RATE_LIMIT_GET = (1, 60)

RATE LIMITING / FIRST REQUEST
$ curl -i <url>
HTTP/1.1 200 OK
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1390486659

RATE LIMITING / SECOND REQUEST
$ curl -i <url>
HTTP/1.1 429 TOO MANY REQUESTS

CONDITIONAL REQUESTS
ALLOW CLIENTS TO ONLY REQUEST NON-CACHED CONTENT
DEMO

IF-MODIFIED-SINCE
If-Modified-Since: Wed, 05 Dec 2012 09:53:07 GMT
“Return document is changed since <date>, or 304 (Not Modified)”

IF-NONE-MATCH
If-None-Match:1234567890123456789012345678901234567890
“Return data if it has changed (ETAG differs from mine), or 304 (Not Modified)”
>

BULK INSERTS
INSERT MULTIPLE DOCUMENTS WITH A SINGLE REQUEST
DEMO

BULK INSERTS / REQUEST
$ curl -d '
[
{
"firstname": "barack",
"lastname": "obama"
},
{
"firstname": "mitt",
"lastname": "romney"
}
]'
-H 'Content-Type: application/json' <url>

BULK INSERTS / RESPONSE
[
{
"_status": "OK",
"_updated": "Thu, 22 Nov 2012 15:22:27 GMT",
"_id": "50ae43339fa12500024def5b",
"_etag": "749093d334ebd05cf7f2b7dbfb7868605578db2c"
"_links": {"self": {"href": "<url>", "title": "person"}}
},
{
"_status": "OK",
"_id": "50ae43339fa12500024def5c",
"_etag": "62d356f623c7d9dc864ffa5facc47dced4ba6907"
}
]
COHERENCE MODE OFF: ONLY META FIELDS ARE RETURNED

BULK INSERTS / RESPONSE
[
{
"_status": "OK",
"_id": "50ae43339fa12500024def5b",
"_etag": "749093d334ebd05cf7f2b7dbfb7868605578db2c"
"_links": {"self": {"href": "<url>", "title": }},
"firstname": "barack",
"lastname": "obama",
…
},
{
"_status": "OK",
"_id": "50ae43339fa12500024def5c",
"firstname": "mitt",
"lastname": "romney",
…
}
] COHERENCE MODE ON: ALL FIELDS RETURNED

DATA INTEGRITY AND
CONCURRENCY CONTROL
NO OVERWRITING OF ANY DOCUMENT WITH OBSOLETE VERSIONS

DATA INTEGRITY AND CONSISTENCY
$ curl -X PATCH -i <url>
-d '{"firstname": "ronald"}'
HTTP/1.1 428 PRECONDITION REQUIRED
IF-MATCH
IS MISSING

-H "If-Match: <obsolete_etag>"
HTTP/1.1 412 PRECONDITION FAILED
ETAG
MISMATCH

-H "If-Match: 206fb4a39815cc0ebf48b2b52d7…”
HTTP/1.1 200 OK
UPDATE ALLOWED:
ETAG MATCH BETWEEN SERVER AND CLIENT

DATA VALIDATION
[
{
"_status": "ERR",
"_issues": {"name": "value 'clinton' not unique"}
},
{
"_status": "OK",
"_id": "50ae43339fa12500024def5c",
"_links": {
"self": {
"href": "<url>",
"title": "person"
}
}
}
]
powered by
Cerberus
python-cerberus.org

GEOJSON
SUPPORT AND VALIDATION FOR GEOJSON TYPES
POINT, LINE-STRING, POLYGON, MULTI-POINT,
MULTILINE-STRING, MULTI-POLYGON, GEOMETRICAL COLLECTION

AUTHENTICATION AND
AUTHORIZATION
BASIC, TOKEN AND HMAC AUTH SUPPORTED

RUNS ON ALL PYTHONS
2.6+ / 3.3+ / PYPY 3

AND MUCH MORE
CORS / CACHE CONTROL / OPLOG / SOFT DELETES
LOGGING / CUSTOM ID FIELDS / JSONP / MULTI-DB / AGGREGATION / ETC.

BSD LICENSED
USE IN BOTH OPEN SOURCE AND COMMERCIAL

CUSTOM DATA LAYERS
BUILD YOUR OWN DATA LAYER

AUTHENTICATION
BASIC | TOKEN | HMAC
DEMO

SECURITY AT A GLANCE
• global authentication
• custom endpoint auth
• public enpoints and methods
• role based access control
• user restricted resource access

TWO.
OVERRIDE CHECK_AUTH() METHOD

THREE.
PASS YOUR CLASS TO EVE APP

CUSTOM VALIDATION
EXTEND THE BUILT-IN VALIDATION SYSTEM

CUSTOM VALIDATION
• add custom data types
• add custom validation
logic
• normalization

EVENT HOOKS
PLUG CUSTOM ACTIONS INTO THE API LOOP
DEMO

EVENT HOOKS AT A GLANCE
• POST on_insert/on_inserted
• GET on_fetch/on_fetched
• PATCH on_update/on_updated
• PUT on_replace/on_replaced
• DELETE on_delete/on_deteled
• on_pre_<method>; on_post_<method>

EVE IS FLASK
CLASSIC FLASK POWER AT YOUR FINGERTIPS
DEMO

FLASK AT YOUR FINGERTIPS
from eve import Eve
app = Eve()
# add a regular Flask endpoint
@app.route('/hello')
def hello_world():
return 'Hello World!'
app.run()

FLASK AT YOUR FINGERTIPS
from eve import Eve
from eve.auth import requires_auth
app = Eve()
# add Eve auth to Flask endpoint
@app.route('/hello')
@requires_auth('resource')
def hello_world():
return 'Hello World!'
app.run()

CUSTOM FILE STORAGE
CUSTOM STORAGE CLASSES: S3 / FILE SYSTEM / ETC.

EVE-SQLALCHEMY
SQL DATA LAYER FOR EVE

EVE-ELASTIC
ELASTICSEARCH DATA LAYER FOR EVE REST FRAMEWORK

EVE-MONGOENGINE
USE MONGOENGINE ORM MODELS WITH EVE

EVE.NET
CROSS PLATFORM ASYNC C# CLIENT

EVE-AUTH-JWT
OAUTH 2.0 JWT VALIDATION AUTHENTICATION

FLASK-SENTINEL
OAUTH2 SERVER (USERS, TOKENS, ETC.)

{124: you name here}
Bryan Cattle Christoph Witzany Daniele Pizzolli
dccrazyboy Dong Wei Ming Florian Rathgeber Francisco
Corrales Morales Garrin Kimmell Gianfranco Palumbo
Jaroslav Semančík Jean Boussier John Deng Jorge Puente
Sarrín Josh Villbrandt Julien Barbot Ken Carpenter
Kevin Bowrin Kracekumar Nicolas Bazire Nicolas Carlier
Ondrej Slinták Petr Jašek Paul Doucet Robert Wlodarczyk Roberto
Pasini Ronan Delacroix Roy Smith Ryan Shea Samuel Sutch
Stanislav Heller Thomas Sileo Tomasz Jezierski Xavi Cubillas

PYTHON-EVE.ORGeveREST WEB API
eve
@nicolaiarocci / nicolaiarocci.com / eve@nicolaiarocci.com

RESTFUL SERVICES MADE EASY: THE EVE REST API FRAMEWORK - Nicola Iarocci - Codemotion Rome 2017

Recommended

More Related Content

What's hot (20)

Similar to RESTFUL SERVICES MADE EASY: THE EVE REST API FRAMEWORK - Nicola Iarocci - Codemotion Rome 2017 (20)

More from Codemotion (20)

Recently uploaded (20)

RESTFUL SERVICES MADE EASY: THE EVE REST API FRAMEWORK - Nicola Iarocci - Codemotion Rome 2017