The document discusses RESTful web services and the Eve framework for building them. It provides an overview of key Eve features like setting up a basic API, connecting to MongoDB, adding validation rules, embedding resources, pagination, filtering, sorting, rate limiting, file storage, and ensuring data integrity. The presentation also covers more advanced topics such as geo-spatial support, authentication, and using Eve with other data stores like SQL and Elasticsearch.

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

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

3. REST API FOR HUMANSeveREST WEB API
eve

4. EVE IS POWERED BY

8. QUICKSTART

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

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

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

12. 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"}
}
}

13. $ 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"}
}
}
HATEOAS AT WORK HERE
TEST YOUR API

14. $ 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"}
}
}
TEST YOUR API
CLIENTS CAN EXPLORE
THE API PROGRAMMATICALLY

15. $ 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"}
}
}
TEST YOUR API
AND EVENTUALLY
FILL THEIR UI

16. $ 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"}
}
}
EMTPY AS WE DIDN’T
CONNECT A DATASOURCE
TEST YOUR API

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

18. DEMO TIME!

19. # 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

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

21. # enable writes. default is ['GET']
# /people
RESOURCE_METHODS = ['GET','POST']
# /people/<id>
ITEM_METHODS = ['GET','PATCH','PUT','DELETE']
SETTINGS.PY
ADD/CREATE ONE OR MORE
ITEMS

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

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

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

25. 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'
}
)

26. FEATURES

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

28. PYTHON FILTERS
?where=lastname==“Doe”

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

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

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

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

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

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

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

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

37. EMBEDDED
$ curl -i <url>?embedded={"author": 1}
HTTP/1.1 200 OK
{
"title": "Book Title",
"description": "book description",
"author": {
"firstname": "Mark",
"lastname": "Green",
}
}
EMBEDDED
DOCUMENT

38. JSON AND XML
SERIALIZATION FOR ALL RESPONSES
DEMO

39. APPLICATION/JSON
[
{
"firstname": "Mark",
"lastname": "Green",
"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",
...
},
]

40. [
{
"firstname": "Mark",
"lastname": "Green",
"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

41. 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>

42. HATEOAS
HYPERMEDIA AS THE ENGINE OF APPLICATION STATE

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

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

45. FILE STORAGE
FILES ARE STORED IN GRIDFS BY DEFAULT

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

47. 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

48. 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

49. 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’]

50. 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"

51. RATE LIMITING
POWERED

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

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

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

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

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

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

58. BULK INSERTS
INSERT MULTIPLE DOCUMENTS WITH A SINGLE REQUEST
DEMO

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

60. 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",
"_updated": "Thu, 22 Nov 2012 15:22:27 GMT",
"_id": "50ae43339fa12500024def5c",
"_etag": "62d356f623c7d9dc864ffa5facc47dced4ba6907"
"_links": {"self": {"href": "<url>", "title": "person"}}
}
]
COHERENCE MODE OFF: ONLY META FIELDS ARE RETURNED

61. BULK INSERTS / RESPONSE
[
{
"_status": "OK",
"_updated": "Thu, 22 Nov 2012 15:22:27 GMT",
"_id": "50ae43339fa12500024def5b",
"_etag": "749093d334ebd05cf7f2b7dbfb7868605578db2c"
"_links": {"self": {"href": "<url>", "title": }},
"firstname": "barack",
"lastname": "obama",
…
},
{
"_status": "OK",
"_updated": "Thu, 22 Nov 2012 15:22:27 GMT",
"_id": "50ae43339fa12500024def5c",
"_etag": "62d356f623c7d9dc864ffa5facc47dced4ba6907"
"_links": {"self": {"href": "<url>", "title": "person"}}
"firstname": "mitt",
"lastname": "romney",
…
}
] COHERENCE MODE ON: ALL FIELDS RETURNED

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

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

64. $ curl -X PATCH -i <url>
-H "If-Match: <obsolete_etag>"
-d '{"firstname": "ronald"}'
HTTP/1.1 412 PRECONDITION FAILED
ETAG
MISMATCH
DATA INTEGRITY AND CONSISTENCY

65. $ curl -X PATCH -i <url>
-H "If-Match: 206fb4a39815cc0ebf48b2b52d7…”
-d '{"firstname": "ronald"}'
HTTP/1.1 200 OK
UPDATE ALLOWED:
ETAG MATCH BETWEEN SERVER AND CLIENT
DATA INTEGRITY AND CONSISTENCY

66. DATA VALIDATION
[
{
"_status": "ERR",
"_issues": {"name": "value 'clinton' not unique"}
},
{
"_status": "OK",
"_updated": "Thu, 22 Nov 2012 15:22:27 GMT",
"_id": "50ae43339fa12500024def5c",
"_etag": "62d356f623c7d9dc864ffa5facc47dced4ba6907"
"_links": {
"self": {
"href": "<url>",
"title": "person"
}
}
}
]
powered by
Cerberus
python-cerberus.org

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

68. AUTHENTICATION AND
AUTHORIZATION
BASIC, TOKEN AND HMAC AUTH SUPPORTED

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

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

71. BSD LICENSED
USE IN BOTH OPEN SOURCE AND COMMERCIAL

72. DEVELOPERS

73. CUSTOM DATA LAYERS
BUILD YOUR OWN DATA LAYER

74. SQL ALCHEMY

75. ELASTICSERCH

76. MONGO

77. AUTHENTICATION
BASIC | TOKEN | HMAC
DEMO

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

79. THREE STEPS
AUTH TUTORIAL

80. ONE.
IMPORT BASE AUTH CLASS

81. TWO.
OVERRIDE CHECK_AUTH() METHOD

82. THREE.
PASS YOUR CLASS TO EVE APP

83. CUSTOM VALIDATION
EXTEND THE BUILT-IN VALIDATION SYSTEM

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

85. EVENT HOOKS
PLUG CUSTOM ACTIONS INTO THE API LOOP
DEMO

86. 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>

87. TRANSFORM INCOMING DOCUMENTS

88. EVE IS FLASK
CLASSIC FLASK POWER AT YOUR FINGERTIPS
DEMO

89. 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()

90. 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()

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

92. COMMUNITY

93. EVE-SWAGGER
SWAGGER FOR EVE

94. EVE-SWAGGER

95. EVE-SQLALCHEMY
SQL DATA LAYER FOR EVE

96. EVE-ELASTIC
ELASTICSEARCH DATA LAYER FOR EVE REST FRAMEWORK

97. EVE-MONGOENGINE
USE MONGOENGINE ORM MODELS WITH EVE

98. EVE.NET
CROSS PLATFORM ASYNC C# CLIENT

99. EVE-AUTH-JWT
OAUTH 2.0 JWT VALIDATION AUTHENTICATION

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

101. {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

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