KISS REST API

8/3/2019 KISS REST API

1/29

KISS REST API@yurevich, oDesk corp.ekb.py 2012

1


2/29

Plan

K.O.

Good practices

Real world sample

Toolset

2


3/29

Good API

Easy

to use

to read

to extend

Complete

Consistent

3


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


5/29

Good samples

Twitter API

Twilio API

Amazon S3 API

5


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/


7/29

Writing spec

Document it first

Real use-cases

Complete and closed set

Future kills now

Explicit versioning

7


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


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


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


11/29


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/


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


14/29


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


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


17/29

Toolset

Documentation

Backend

Validation

JSON generation

Whats next?

17


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


19/29

Toolset: prototyping

https://github.com/mozilla-services/redbarrel

External DSL (hello, PHP&Ruby)

Self-documented

Easy to distribute

Only for prototyping

19


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


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


22/29

Django+TastyPie

A lot of features

Pure Resource, ModelResource

Pagination

In our team richest APIs are implementedin TastyPie

22


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/


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


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


26/29


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/


28/29

Surprise

Dzen Python works for REST APIs

curl http://pure-dawn-9186.herokuapp.com/

import-this

28


29/29

Thanks

Questions?

[email protected]

follow me on twitter @yurevich

Date post:	06-Apr-2018
Category:	Documents
Upload:	yury-yurevich
View:	244 times
Download:	0 times

KISS REST API

Documents