Building RESTful APIs - Speaker Deck

Slide 1

Slide 1 text

Building Better Web APIs Sunday, 30 September 12

Slide 2

Slide 2 text

Building better Web APIs whoami • Hemant - (AKA Ruby guy). • http://github.com/gnuﬁed • http://www.codemancers.com Sunday, 30 September 12

Slide 3

Slide 3 text

Building better Web APIs What is REST? Sunday, 30 September 12

Slide 4

Slide 4 text

Building better Web APIs What is REST? REST is a software architectural style for network based application software. Sunday, 30 September 12

Slide 5

Slide 5 text

Building better Web APIs What is REST? REST is a software architectural style for network based application software. Roy Fielding Sunday, 30 September 12

Slide 6

Slide 6 text

Building better Web APIs Few important things Sunday, 30 September 12

Slide 7

Slide 7 text

Building better Web APIs Few important things • It is not a design pattern. Sunday, 30 September 12

Slide 8

Slide 8 text

Building better Web APIs Few important things • It is not a design pattern. • It is not a library or framework. Sunday, 30 September 12

Slide 9

Slide 9 text

Building better Web APIs Using HTTP to its fullest to interact with resources within certain Architectural constraints. Sunday, 30 September 12

Slide 10

Slide 10 text

Building better Web APIs http://tomayko.com/writings/rest-to-my-wife Sunday, 30 September 12

Slide 11

Slide 11 text

Building better Web APIs Sunday, 30 September 12

Slide 12

Slide 12 text

Building better Web APIs A web page is a “representation” of a resource. Loving husband to his wife Sunday, 30 September 12

Slide 13

Slide 13 text

Building better Web APIs Resource as abstract entity Any information that can be named is a resource. For example - document, images. Sunday, 30 September 12

Slide 14

Slide 14 text

Building better Web APIs Identify resources in your Application Sunday, 30 September 12

Slide 15

Slide 15 text

Building better Web APIs REST anti-pattern Sunday, 30 September 12

Slide 16

Slide 16 text

Building better Web APIs REST anti-pattern • Each database model is turned into a Resource. Sunday, 30 September 12

Slide 17

Slide 17 text

Building better Web APIs REST anti-pattern • Each database model is turned into a Resource. • Trying hard to model API after your database design. Sunday, 30 September 12

Slide 18

Slide 18 text

Building better Web APIs Identify resources in your Application Sunday, 30 September 12

Slide 19

Slide 19 text

Building better Web APIs Identify resources in your Application • Think about what your webservice provides. Sunday, 30 September 12

Slide 20

Slide 20 text

Building better Web APIs Identify resources in your Application • Think about what your webservice provides. • And work backwards from that. Sunday, 30 September 12

Slide 21

Slide 21 text

Building better Web APIs Flipkart Sunday, 30 September 12

Slide 22

Slide 22 text

Building better Web APIs Flipkart Books Sunday, 30 September 12

Slide 23

Slide 23 text

Building better Web APIs Flipkart Books Users Sunday, 30 September 12

Slide 24

Slide 24 text

Building better Web APIs Flipkart Books Users Reviews Sunday, 30 September 12

Slide 25

Slide 25 text

Building better Web APIs Flipkart Books Users Reviews Prices Sunday, 30 September 12

Slide 26

Slide 26 text

Building better Web APIs But then again Sunday, 30 September 12

Slide 27

Slide 27 text

Building better Web APIs Sunday, 30 September 12

Slide 28

Slide 28 text

Building better Web APIs Books Sunday, 30 September 12

Slide 29

Slide 29 text

Building better Web APIs Books Reviews Sunday, 30 September 12

Slide 30

Slide 30 text

Building better Web APIs Books Reviews Prices Sunday, 30 September 12

Slide 31

Slide 31 text

Building better Web APIs Books Reviews Prices Sunday, 30 September 12

Slide 32

Slide 32 text

Building better Web APIs Books Reviews Prices Sunday, 30 September 12

Slide 33

Slide 33 text

Building better Web APIs Books Reviews Prices Sunday, 30 September 12

Slide 34

Slide 34 text

Building better Web APIs Books Reviews Prices Tables Sunday, 30 September 12

Slide 35

Slide 35 text

Building better Web APIs Sunday, 30 September 12

Slide 36

Slide 36 text

Building better Web APIs Resources Tables Sunday, 30 September 12

Slide 37

Slide 37 text

Building better Web APIs Why is that bad? Sunday, 30 September 12

Slide 38

Slide 38 text

Building better Web APIs • Tight coupling with Data model. Why is that bad? Sunday, 30 September 12

Slide 39

Slide 39 text

Building better Web APIs • Tight coupling with Data model. • You are on a slippery slope now. Why is that bad? Sunday, 30 September 12

Slide 40

Slide 40 text

Building better Web APIs Example Sunday, 30 September 12

Slide 41

Slide 41 text

Building better Web APIs POST "/company.json" Params : { "user_attributes": { "name": "Hemant Kumar", "password": "password", "password_confirmation": "password", "email": "[email protected]" }, "company_attributes": { "name": "Codemancers Technologies", "address": "blah blah" } "payment_attribtutes": { "credit_card": { "number": "4242" }, "amount": "42" } } Sunday, 30 September 12

Slide 42

Slide 42 text

Building better Web APIs What was wrong? Sunday, 30 September 12

Slide 43

Slide 43 text

Building better Web APIs What was wrong? • Any guesses why creating a company via API required so many parameters? Sunday, 30 September 12

Slide 44

Slide 44 text

Building better Web APIs What was wrong? • Any guesses why creating a company via API required so many parameters? • Not clear we are dealing with which “resource” exactly there. Sunday, 30 September 12

Slide 45

Slide 45 text

Building better Web APIs def create @company = Company.new(params[:company]) respond_to do |format| format.html { if @company.save ... else ... end } format.json { if @company.save .... else ... end } end end HTML request JSON request Sunday, 30 September 12

Slide 46

Slide 46 text

Building better Web APIs Thats how we built APIs using Rails Sunday, 30 September 12

Slide 47

Slide 47 text

Building better Web APIs Sunday, 30 September 12

Slide 48

Slide 48 text

Building better Web APIs Sunday, 30 September 12

Slide 49

Slide 49 text

Building better Web APIs Sadly it is still RESTful architecture for many Rails developers. Sunday, 30 September 12

Slide 50

Slide 50 text

Building better Web APIs REST Anti-Pattern A REST API must not deﬁne ﬁxed resource names or hierarchies (an obvious coupling of client and server). Sunday, 30 September 12

Slide 51

Slide 51 text

Building better Web APIs REST Anti-Pattern A REST API must not deﬁne ﬁxed resource names or hierarchies (an obvious coupling of client and server). /users/1/posts/1/comments.json Sunday, 30 September 12

Slide 52

Slide 52 text

Building better Web APIs Recap • Identify resources to expose. • Expose the workﬂow not the data model. Sunday, 30 September 12

Slide 53

Slide 53 text

Building better Web APIs Questions? Sunday, 30 September 12

Slide 54

Slide 54 text

Building better Web APIs Using HTTP to fullest Sunday, 30 September 12

Slide 55

Slide 55 text

Building better Web APIs REST is not speciﬁc to building APIs Sunday, 30 September 12

Slide 56

Slide 56 text

Building better Web APIs Using HTTP verbs Sunday, 30 September 12

Slide 57

Slide 57 text

Building better Web APIs Sunday, 30 September 12

Slide 58

Slide 58 text

Building better Web APIs • GET Sunday, 30 September 12

Slide 59

Slide 59 text

Building better Web APIs • GET • POST Sunday, 30 September 12

Slide 60

Slide 60 text

Building better Web APIs • GET • POST • PUT Sunday, 30 September 12

Slide 61

Slide 61 text

Building better Web APIs • GET • POST • PUT • DELETE Sunday, 30 September 12

Slide 62

Slide 62 text

Building better Web APIs Django’s function based views suck Sunday, 30 September 12

Slide 63

Slide 63 text

Building better Web APIs Anyone actually uses that? Sunday, 30 September 12

Slide 64

Slide 64 text

Building better Web APIs Sunday, 30 September 12

Slide 65

Slide 65 text

Building better Web APIs # API for posts @app.route('/',methods = 'GET') def index(): .. @app.route('/', methods = 'POST') def create(): .. @app.route('/post/', methods = 'PUT') def update(): .. @app.route('/post/', methods = 'DELETE') def destroy(): .. Sunday, 30 September 12

Slide 66

Slide 66 text

Building better Web APIs How do I do this in Ruby? Sunday, 30 September 12

Slide 67

Slide 67 text

Building better Web APIs resources :devices do get do # /devices/1 .. end post do # /devices .. end put do # /devices/1 .. end delete do # /devices/1 .. end end https://github.com/intridea/grape Sunday, 30 September 12

Slide 68

Slide 68 text

Building better Web APIs So what is the big fuss about verbs? Sunday, 30 September 12

Slide 69

Slide 69 text

Building better Web APIs Only support GET & POST Sunday, 30 September 12

Slide 70

Slide 70 text

Building better Web APIs GET Sunday, 30 September 12

Slide 71

Slide 71 text

Building better Web APIs GET • Anything that is safe. Does not have side eﬀects. Sunday, 30 September 12

Slide 72

Slide 72 text

Building better Web APIs GET • Anything that is safe. Does not have side eﬀects. • Can be cached, bookmarked, linked, proxied. Sunday, 30 September 12

Slide 73

Slide 73 text

Building better Web APIs POST Sunday, 30 September 12

Slide 74

Slide 74 text

Building better Web APIs POST • It can do anything. Sunday, 30 September 12

Slide 75

Slide 75 text

Building better Web APIs POST • It can do anything. • You do not pre-fetch it, you don’t bookmark it, you don’t cache it. Sunday, 30 September 12

Slide 76

Slide 76 text

Building better Web APIs POST • It can do anything. • You do not pre-fetch it, you don’t bookmark it, you don’t cache it. • You do not build Web protocols on it. (*hint*) Sunday, 30 September 12

Slide 77

Slide 77 text

Building better Web APIs Sunday, 30 September 12

Slide 78

Slide 78 text

Building better Web APIs PUT Sunday, 30 September 12

Slide 79

Slide 79 text

Building better Web APIs PUT • Updates a resource. Sunday, 30 September 12

Slide 80

Slide 80 text

Building better Web APIs PUT • Updates a resource. • Is idempotent. Sunday, 30 September 12

Slide 81

Slide 81 text

Building better Web APIs PUT • Updates a resource. • Is idempotent. DELETE Sunday, 30 September 12

Slide 82

Slide 82 text

Building better Web APIs PUT • Updates a resource. • Is idempotent. DELETE • Deletes a resource. Sunday, 30 September 12

Slide 83

Slide 83 text

Building better Web APIs PUT • Updates a resource. • Is idempotent. DELETE • Deletes a resource. • Ist idempotent. Sunday, 30 September 12

Slide 84

Slide 84 text

Building better Web APIs PUT • Updates a resource. • Is idempotent. DELETE • Deletes a resource. • Ist idempotent. Sunday, 30 September 12

Slide 85

Slide 85 text

Building better Web APIs Use HTTP response codes wisely • 200 - OK • 201 - created • 202 - accepted • 409 - conﬂict • 422 - Unprocessable entity • 401 - Unauthorized • 404 - Resource not found Sunday, 30 September 12

Slide 86

Slide 86 text

Building better Web APIs Questions? Sunday, 30 September 12

Slide 87

Slide 87 text

Building better Web APIs Media Type A REST API should spend almost all of its descriptive eﬀort in deﬁning the media type(s) used Roy Fielding Sunday, 30 September 12

Slide 88

Slide 88 text

Building better Web APIs Evolvability Sunday, 30 September 12

Slide 89

Slide 89 text

Building better Web APIs Client Server Contract Media Type Sunday, 30 September 12

Slide 90

Slide 90 text

Building better Web APIs Mime Types Sunday, 30 September 12

Slide 91

Slide 91 text

Building better Web APIs Examples • Well known - text/html, application/json, text/ xml • Custom or vendor speciﬁc - application/ vnd.github+json Sunday, 30 September 12

Slide 92

Slide 92 text

Building better Web APIs application/json • Preferred mime-type for APIs. • Formatting your hypermedia is most important thing. Sunday, 30 September 12

Slide 93

Slide 93 text

Building better Web APIs Elephant in the room Sunday, 30 September 12

Slide 94

Slide 94 text

Building better Web APIs Warning signs Sunday, 30 September 12

Slide 95

Slide 95 text

Building better Web APIs Warning signs A REST API should not deﬁne ﬁxed resource names. Sunday, 30 September 12

Slide 96

Slide 96 text

Building better Web APIs /users/1/posts Sunday, 30 September 12

Slide 97

Slide 97 text

Building better Web APIs /users/1/posts Wrong Sunday, 30 September 12

Slide 98

Slide 98 text

Building better Web APIs Warning Sign A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types. Sunday, 30 September 12

Slide 99

Slide 99 text

Building better Web APIs Warning Sign A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types. You should never have to document API end points. Sunday, 30 September 12

Slide 100

Slide 100 text

Building better Web APIs Warning Sign API versioning is a Anti-Pattern. Sunday, 30 September 12

Slide 101

Slide 101 text

Building better Web APIs Warning Signs Allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by deﬁning those instructions within media types and link relations. Sunday, 30 September 12

Slide 102

Slide 102 text

Slide 103

Slide 103 text

Building better Web APIs API should be discoverable Sunday, 30 September 12

Slide 104

Slide 104 text

Building better Web APIs Hypermedia as Engine of Application State Sunday, 30 September 12

Slide 105

Slide 105 text

Building better Web APIs 99% of APIs out there are RESTlike Sunday, 30 September 12

Slide 106

Slide 106 text

Building better Web APIs http://martinfowler.com/articles/richardsonMaturityModel.html Sunday, 30 September 12

Slide 107

Slide 107 text

Building better Web APIs Book an appointment with Doctor Sunday, 30 September 12

Slide 108

Slide 108 text

Building better Web APIs Sunday, 30 September 12

Slide 109

Slide 109 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Sunday, 30 September 12

Slide 110

Slide 110 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Sunday, 30 September 12

Slide 111

Slide 111 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 112

Slide 112 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 113

Slide 113 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 114

Slide 114 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 115

Slide 115 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 116

Slide 116 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Sunday, 30 September 12

Slide 117

Slide 117 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Description Sunday, 30 September 12

Slide 118

Slide 118 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Description Sunday, 30 September 12

Slide 119

Slide 119 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Description URI Sunday, 30 September 12

Slide 120

Slide 120 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Description URI Sunday, 30 September 12

Slide 121

Slide 121 text

Building better Web APIs GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Date Description URI Verb Sunday, 30 September 12

Slide 122

Slide 122 text

Building better Web APIs Sunday, 30 September 12

Slide 123

Slide 123 text

Building better Web APIs Sunday, 30 September 12

Slide 124

Slide 124 text

Building better Web APIs Sunday, 30 September 12

Slide 125

Slide 125 text

Building better Web APIs Sunday, 30 September 12

Slide 126

Slide 126 text

Building better Web APIs Sunday, 30 September 12

Slide 127

Slide 127 text

Building better Web APIs What does HATEOAS provide? • You never have to version your API. • You never have to worry about changing resource names. • Beyond initial URL, never have to worry about keeping old endpoints intact. Sunday, 30 September 12

Slide 128

Slide 128 text

Building better Web APIs Why aren’t people doing this? Sunday, 30 September 12

Slide 129

Slide 129 text

Building better Web APIs Usage of Hypermedia Controls? • Tooling • Lack of education among programmers. Sunday, 30 September 12

Slide 130

Slide 130 text

Building better Web APIs Widely deployed REST system The Web Sunday, 30 September 12

Slide 131

Slide 131 text

Building better Web APIs Questions? Sunday, 30 September 12

Slide 132

Slide 132 text

Building better Web APIs Versioning Sunday, 30 September 12

Slide 133

Slide 133 text

Building better Web APIs Lack of Hypermedia Controls forces us to have versioning Sunday, 30 September 12

Slide 134

Slide 134 text

Building better Web APIs Two dominant ways • github.com/api/v3/users.json • Mime-type based versioning : application/ vnd.github[.version].param[+json] Sunday, 30 September 12

Slide 135

Slide 135 text

Building better Web APIs Using Mime-Type class Twitter::API < Grape::API version 'v1', :using => :header, :vendor => 'pycon' end curl -H Accept=application/vnd.pycon-v1+json http://localhost:9292/users Sunday, 30 September 12

Slide 136

Slide 136 text

Building better Web APIs Using PATH class Twitter::API < Grape::API version 'v1', :using => :path end curl -H Accept=application/json http://localhost:9292/v1/users Sunday, 30 September 12

Slide 137

Slide 137 text

Building better Web APIs Questions? Sunday, 30 September 12

Slide 138

Slide 138 text

Building better Web APIs Thank you. http://twitter.com/gnuﬁed Sunday, 30 September 12