KISS REST API
-
Upload
yury-yurevich -
Category
Documents
-
view
248 -
download
0
Transcript of KISS REST API
-
8/3/2019 KISS REST API
1/29
KISS REST API@yurevich, oDesk corp.ekb.py 2012
1
-
8/3/2019 KISS REST API
2/29
Plan
K.O.
Good practices
Real world sample
Toolset
2
-
8/3/2019 KISS REST API
3/29
Good API
Easy
to use
to read
to extend
Complete
Consistent
3
-
8/3/2019 KISS REST API
4/29
REST
stateless (no cookies & sessions)
resources identification (URLs)
representation (JSON, XML, YaML)
manipulation of resources through
representation self-descriptive messages
hypermedia (Links)
4
-
8/3/2019 KISS REST API
5/29
Good samples
Twitter API
Twilio API
Amazon S3 API
5
-
8/3/2019 KISS REST API
6/29
Good practices
Though not so universal
http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/
http://jacobian.org/writing/rest-worst-practices/
6
http://jacobian.org/writing/rest-worst-practices/http://jacobian.org/writing/rest-worst-practices/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://jacobian.org/writing/rest-worst-practices/http://jacobian.org/writing/rest-worst-practices/http://jacobian.org/writing/rest-worst-practices/http://jacobian.org/writing/rest-worst-practices/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-web-services/ -
8/3/2019 KISS REST API
7/29
Writing spec
Document it first
Real use-cases
Complete and closed set
Future kills now
Explicit versioning
7
-
8/3/2019 KISS REST API
8/29
Beginners mistakes
Resource = model
Think about married couple
All methods should be implemented forevery resource
Update user account activation? Deletesent SMS message?
Custom methods
8
-
8/3/2019 KISS REST API
9/29
Use nouns
learn assive voice User sends SMS message =>
A SMS message is created
Article is reviewed by editor =>Review of article is created
The user deactivates account =>User account activation is deleted
9
-
8/3/2019 KISS REST API
10/29
Namespaces
https://smsgate/v2/messages(or https://smsgate/20120210/messages) VShttps://smsgate/messages
10
https://smsgate/messagehttps://smsgate/messagehttps://smsgate/messagehttp://smsgate/20120210/messagehttp://smsgate/20120210/messagehttp://smsgate/v2/messagehttp://smsgate/v2/message -
8/3/2019 KISS REST API
11/29
-
8/3/2019 KISS REST API
12/29
URLs
Required GET params must be part of URL
http://smsgate/v2/messages/{id} instead ofhttp://smsgate/v2/message?id={id}
12
http://smsgate/v2/message?id=%7Bhttp://smsgate/v2/message?id=%7Bhttp://smsgate/v2/message?id=%7Bhttp://smsagate/http://smsagate/ -
8/3/2019 KISS REST API
13/29
Auth! SSL!
https://smsgate/v2/messages VShttp://smsgate/v2/messages
Poor man auth: token-based
Production ready: oAuth2
13
http://smsgate/v2/messageshttp://smsgate/v2/messageshttps://smsgate/v2/messageshttps://smsgate/v2/messages -
8/3/2019 KISS REST API
14/29
-
8/3/2019 KISS REST API
15/29
Real world sample
SMS Gate
Resource: Text Message /message:
Create new one (send) POST /messages
Get information about statusGET /messages/{id}
version: 2
15
-
8/3/2019 KISS REST API
16/29
Real world sample 2
POST https://smsgate2/v2/messages> message=Send%20it
%20please&target=780020000000
201 CreatedLocation: https://smsgate2/v2/messages/242
{target: 78002000000, url: https://smsgate2/v2/messages/242, status:queued}
16
https://smsgate2/v2/messagehttps://smsgate2/v2/messagehttps://smsgate2/v2/messagehttps://smsgate2/v2/messagehttps://smsgate2/v2/messagehttps://smsgate2/v2/message -
8/3/2019 KISS REST API
17/29
Toolset
Documentation
Backend
Validation
JSON generation
Whats next?
17
-
8/3/2019 KISS REST API
18/29
Toolset: documentation
Sphinx (ReST)
HTTP Domain https://github.com/
deceze/Sphinx-HTTP-domain
httpdomain https://bitbucket.org/birkenfeld/sphinx-contrib
Markdown
https://github.com/coopernurse/doctorj
18
https://github.com/coopernurse/doctorjhttps://github.com/coopernurse/doctorjhttps://bitbucket.org/birkenfeld/sphinx-contribhttps://github.com/deceze/Sphinx-HTTP-domainhttps://github.com/coopernurse/doctorjhttps://github.com/coopernurse/doctorjhttps://bitbucket.org/birkenfeld/sphinx-contribhttps://bitbucket.org/birkenfeld/sphinx-contribhttps://bitbucket.org/birkenfeld/sphinx-contribhttps://bitbucket.org/birkenfeld/sphinx-contribhttps://github.com/deceze/Sphinx-HTTP-domainhttps://github.com/deceze/Sphinx-HTTP-domainhttps://github.com/deceze/Sphinx-HTTP-domainhttps://github.com/deceze/Sphinx-HTTP-domain -
8/3/2019 KISS REST API
19/29
Toolset: prototyping
https://github.com/mozilla-services/redbarrel
External DSL (hello, PHP&Ruby)
Self-documented
Easy to distribute
Only for prototyping
19
-
8/3/2019 KISS REST API
20/29
Flask
Simple
You get what you need
A lot of bootstrapping code
Attention to details
Chance to get hardcoded result
In our projects most load-intensive APIs areimplemented using Flask
20
-
8/3/2019 KISS REST API
21/29
Django+Piston
Good set of features (for that time)
Built-in formatters
works well, on Accept header
Methods are strictly mapped to actions
Hard to reuse different forms in singlehandler
Its obsolete
21
-
8/3/2019 KISS REST API
22/29
Django+TastyPie
A lot of features
Pure Resource, ModelResource
Pagination
In our team richest APIs are implementedin TastyPie
22
-
8/3/2019 KISS REST API
23/29
Toolset: Validation
http://bitbucket.org/jek/flatland/
Looks cool
Not so obvious for nested structures
Internals OMG
23
http://bitbucket.org/jek/flatland/http://bitbucket.org/jek/flatland/ -
8/3/2019 KISS REST API
24/29
Toolset: Validation
https://github.com/Deepwalker/procrustes
Data and forms validation
Simple
Good as prototype, not so good for
production
lack of documentation
24
https://github.com/Deepwalker/procrusteshttps://github.com/Deepwalker/procrustes -
8/3/2019 KISS REST API
25/29
Toolset: Validation
https://github.com/Deepwalker/trafaret
Very nice syntax
Easy but supports complex nestedstructures
Lack of documentation
No forms validation
25
https://github.com/Deepwalker/trafarethttps://github.com/Deepwalker/trafaret -
8/3/2019 KISS REST API
26/29
-
8/3/2019 KISS REST API
27/29
Whats next?
JSON Schema
Validation
Discovery
http://json-schema.org/
http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/
http://shane.caraveo.com/2011/06/30/using-
json-schema-for-exploring-api-servers/27
http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://json-schema.org/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://shane.caraveo.com/2011/06/30/using-json-schema-for-exploring-api-servers/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://nico.vahlas.eu/2010/04/23/json-schema-specifying-and-validating-json-data-structures/http://json-schema.org/http://json-schema.org/ -
8/3/2019 KISS REST API
28/29
Surprise
Dzen Python works for REST APIs
curl http://pure-dawn-9186.herokuapp.com/
import-this
28
-
8/3/2019 KISS REST API
29/29
Thanks
Questions?
follow me on twitter @yurevich