KISS REST API@yurevich, oDesk corp.

ekb.py 2012

1

Plan

• K.O.

• Good practices

• Real world sample

• Toolset

2

Good API

• Easy

• to use

• to read

• to extend

• Complete

• Consistent

3

REST

• stateless (no cookies & sessions)

• resources identification (URLs)

• representation (JSON, XML, YaML)

• manipulation of resources through representation

• self-descriptive messages

• hypermedia (Links)

4

Good samples

• Twitter API

• Twilio API

• Amazon S3 API

5

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

Writing specDocument it first

• Real use-cases

• Complete and closed set

• Future kills now

• Explicit versioning

7

Beginners mistakes

• Resource = model

• Think about married couple

• All methods should be implemented for every resource

• Update user account activation? Delete sent SMS message?

• Custom methods

8

Use nouns(learn passive 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

Namespaces

• https://smsgate/v2/messages(or https://smsgate/20120210/messages) VS https://smsgate/messages

10

Resources

• Resources are NOUNs

• https://smsgate/v2/messages VShttps://smsgate/v2/send-message

11

URLs

• Required GET params must be part of URL

• http://smsgate/v2/messages/{id} instead of http://smsgate/v2/message?id={id}

12

Auth! SSL!

• https://smsgate/v2/messages VShttp://smsgate/v2/messages

• Poor man auth: token-based

• Production ready: oAuth2

13

Real world sample 0

• SMS Gate

• GET http://smsgate/sendMessage?number=780020000000&text=Send+it+please

14

Real world sample

• SMS Gate

• Resource: Text Message /message:

• Create new one (send) —POST /messages

• Get information about statusGET /messages/{id}

• version: 2

15

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/message’, ‘status’: ‘queued’}

16

Toolset

• Documentation

• Backend

• Validation

• JSON generation

• What’s next?

17

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

Toolset: prototyping

• Red barrel

• External DSL (hello, PHP&Ruby)

• Self-documented

• Easy to distribute

• Only for prototyping

19

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 are implemented using Flask

20

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 single handler

• It’s obsolete

21

Django+TastyPie

• A lot of features

• Pure Resource, ModelResource

• Pagination

• In our team richest APIs are implemented in TastyPie

22

Toolset: Validation

• http://bitbucket.org/jek/flatland/

• Looks cool

• Not so obvious for nested structures

• Internals — OMG

23

Toolset: Validation

• https://github.com/Deepwalker/procrustes

• Data and forms validation

• Simple

• Good as prototype, not so good for production

• lack of documentation

24

Toolset: Validation

• https://github.com/Deepwalker/trafaret

• Very nice syntax

• Easy but supports complex nested structures

• Lack of documentation

• No forms validation

25

Toolset: JSON writer

• /dev/hands

• Ruby:

• https://github.com/inem/tequila

• https://github.com/nesquena/rabl

26

What’s 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

Surprise

• Dzen Python works for REST APIs

•curl http://pure-dawn-9186.herokuapp.com/import-this

28

Thanks

• Questions?

• yyurevich@jellycrystal.com

• follow me on twitter @yurevich

29