Mobile APIs: More than just object.to_json

Almost all apps rely on APIs, no app is an island, entire of itself. We want to keep our apps slick and simple, pushing complex logic to the server, allowing iOS devs to focus on shiny new user experiences. At realestate.com.au, we're building simpler apps backed by smarter microservices using REST, hypermedia and HATEOAS, not just object.to_json. This session will demonstrate how to quickly build iOS apps that discover, consume and navigate these services using HAL JSON and Objective C libraries we love like AFNetworking and ReactiveCocoa in a way 'future you' will be thankful for. There will be at least one obligatory Australian reference to Crocodile Dundee.

Transcript

1. Mobile APIs: More than just object.to_json Stewart Gleadow @stewgleadow REA Group http://www.flickr.com/photos/markselliott/48699538/
2. Stewart Gleadow @stewgleadow REA Group http://www.flickr.com/photos/markselliott/48699538/ NO APP IS AN ISLAND
4. The app is just the tip of the iceber
5. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
6. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
7. THE EVOLUTION OF WEB SERVICES
8. Is there an API for that?
9. Can I see your API?
10. POST /InStock HTTP/1.1 Host: www.example.org Content-Type: application/soap+xml; charset=utf-8 Content-Length: 299 SOAPAction: "http://www.w3.org/2003/05/soap-envelope" <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> </soap:Header> <soap:Body> <m:GetStockPrice xmlns:m="http://www.example.org/stock"> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body> </soap:Envelope>
11. We have a REST API, just construct one of these “RESTful calls”
15. http://schmidtbrotherscutlery.com/blo /ta /crocodile-dundee/ THAT’S NOT AN API
16. How should we build our API?
17. Level 0 Level 1 Level 2 Level 3
18. Level 0 Level 1 Level 2 Level 3 The swamp of POX
19. Level 0 Level 1 Level 2 Level 3 The swamp of POX URIs and Resources
20. Level 0 Level 1 Level 2 Level 3 The swamp of POX URIs and Resources HTTP verbs and status codes
21. Level 0 Level 1 Level 2 Level 3 The swamp of POX URIs and Resources HTTP verbs and status codes Hypermedia controls
22. Roy Fieldin - http://roy. biv.com/untan led/2008/rest-apis-must-be-hypertext-driven
23. “What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?” Roy Fieldin - http://roy. biv.com/untan led/2008/rest-apis-must-be-hypertext-driven
24. “What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?” Roy Fieldin - http://roy. biv.com/untan led/2008/rest-apis-must-be-hypertext-driven “Is there some broken manual somewhere that needs to be fixed?”
25. “What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?” Roy Fieldin - http://roy. biv.com/untan led/2008/rest-apis-must-be-hypertext-driven “Is there some broken manual somewhere that needs to be fixed?” “Please try to adhere to them or choose some other buzzword for your API.”
26. http://www.flickr.com/photos/50144889@N08/8711099493/ This uy is possibly an island…
27. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
28. Paths to resources within a service chan e
29. Paths to resources within a service chan e get '/Services/Service.axd*' do redirect to('/services') end
30. The location of service endpoints chan e
31. The location of service endpoints chan e http://api.realestate.com.au/suggest http://suggest.realestate.com.au
32. HAL JSON: Standardized hypermedia links in JSON
33. { results : [ { ... listing 1 ... }, { ... listing 2 ... } ], _links : { next : { name : “Next page of search results”, href : “http://services.realestate.com.au/search?page=2” }, self : { name : “Refresh this page of search results”, href : “http://services.realestate.com.au/search?page=1” } } }
35. Example: Sign in and retrieve user details
36. POST “http://example.com/session” { email : "dundee", password : "password" } HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd” } Sign in request Sign in response
37. POST “http://example.com/session” { email : "dundee", password : "password" } HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd” } Which actions are available now? Where do I perform those actions? Sign in request Sign in response
38. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; Sign in & get details from an iOS client
39. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; NSString *detailsUrl = [NSString stringWithFormat:@"http://example.com/details?id=%@", self.userId]; [self.manager GET:detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
40. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; NSString *detailsUrl = [NSString stringWithFormat:@"http://example.com/details?id=%@", self.userId]; [self.manager GET:detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
41. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; NSString *detailsUrl = [NSString stringWithFormat:@"http://example.com/details?id=%@", self.userId]; [self.manager GET:detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
42. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; NSString *detailsUrl = [NSString stringWithFormat:@"http://example.com/details?id=%@", self.userId]; [self.manager GET:detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
43. Response HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd”, _links : { details : { href : “http://example.com/users/c3Rld0ByZWEtZ3Jvd/details” } } }
44. Response HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd”, _links : { details : { href : “http://example.com/users/c3Rld0ByZWEtZ3Jvd/details” } } } Which actions are available now? Where do I perform those actions?
45. Response HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd”, _links : { details : { href : “http://example.com/users/c3Rld0ByZWEtZ3Jvd/details” } } } Which actions are available now? Where do I perform those actions?
46. Response HTTP/1.1 201 Created { user_id : “c3Rld0ByZWEtZ3Jvd”, _links : { details : { href : “http://example.com/users/c3Rld0ByZWEtZ3Jvd/details” } } } Which actions are available now? Where do I perform those actions?
47. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.userId = response[@"user_id"]; } failure:nil]; NSString *detailsUrl = [NSString stringWithFormat:@"http://example.com/details?id=%@", self.user_id]; [self.manager GET:detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
48. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.detailsUrl = response[@"_links"][@"details"][@"href"]; } failure:nil]; [self.manager GET:self.detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
49. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.detailsUrl = response[@"_links"][@"details"][@"href"]; } failure:nil]; [self.manager GET:self.detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
50. NSDictionary *params = @{ @"email" : @"dundee", @"password" : @"password" }; self.manager = [AFHTTPRequestOperationManager manager]; [self.manager POST:@"http://example.com/session" parameters:params success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.detailsUrl = response[@"_links"][@"details"][@"href"]; } failure:nil]; [self.manager GET:self.detailsUrl parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:nil]; Sign in & get details from an iOS client
51. Create discoverable service endpoints http://commons.wikimedia.or /wiki/File:World_Map_1689.JPG
52. GET “http://example.com/services” ... HTTP/1.1 200 OK { _links : { signIn : { name : “Authenticate a user”, href : “http://example.com/session” }, suggest : { name : “Retrieve suburb suggestions matching a string”, href : “http://suggest.realestate.com.au/suggest{?query}”, templated : true }, ... } }
53. GET “http://example.com/services” ... HTTP/1.1 200 OK { _links : { signIn : { name : “Authenticate a user”, href : “http://example.com/session” }, suggest : { name : “Retrieve suburb suggestions matching a string”, href : “http://suggest.realestate.com.au/suggest{?query}”, templated : true }, ... } }
54. [self.manager GET:@"http://example.com/services" parameters:nil success:^(AFHTTPRequestOperation *op, NSDictionary *response) { self.signInEndpoint = response[@"_links"][@"signIn"][@"href"]; self.suggestEndpoint = ... } failure:nil]; Consuming discoverable endpoints
55. Chainin multiple requests ets messy
56. [self.manager GET:@"http://example.com/services" parameters:nil success:^(AFHTTPRequestOperation *op1, NSDictionary *servicesResponse) { NSString *signInEndpoint = servicesResponse[@"_links"][@"signIn"][@"href"]; [self.manager POST:signInEndpoint parameters:params success:^(AFHTTPRequestOperation *op2, NSDictionary *signInResponse) { NSString *detailsEndpoint = signInResponse[@"_links"][@"details"][@"href"]; [self.manager GET:detailsEndpoint parameters:nil success:^(AFHTTPRequestOperation *op3, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:^(AFHTTPRequestOperation *op3, NSError *error) { self.status.text = @"Failed to get user details."; }]; } failure:^(AFHTTPRequestOperation *op2, NSError *error) { self.status.text = @"Failed to sign in."; }]; } failure:^(AFHTTPRequestOperation *op1, NSError *error) { self.status.text = @"Failed to configure service"; }]; Chainin multiple requests ets messy
57. [self.manager GET:@"http://example.com/services" parameters:nil success:^(AFHTTPRequestOperation *op1, NSDictionary *servicesResponse) { NSString *signInEndpoint = servicesResponse[@"_links"][@"signIn"][@"href"]; [self.manager POST:signInEndpoint parameters:params success:^(AFHTTPRequestOperation *op2, NSDictionary *signInResponse) { NSString *detailsEndpoint = signInResponse[@"_links"][@"details"][@"href"]; [self.manager GET:detailsEndpoint parameters:nil success:^(AFHTTPRequestOperation *op3, NSDictionary *response) { self.name.text = response[@"name"]; self.phone.text = response[@"phone"]; } failure:^(AFHTTPRequestOperation *op3, NSError *error) { self.status.text = @"Failed to get user details."; }]; } failure:^(AFHTTPRequestOperation *op2, NSError *error) { self.status.text = @"Failed to sign in."; }]; } failure:^(AFHTTPRequestOperation *op1, NSError *error) { self.status.text = @"Failed to configure service"; }]; Chainin multiple requests ets messy
58. ReactiveCocoa to the rescue
59. NSString *services = @"http://example.com/services"; RACSignal *userDetailsSignal = [[[[[[self.manager rac_getPath:services] map:^NSString *(NSDictionary *response) { return response[@"_links"][@"signIn"][@"href"]; }] flattenMap:^RACSignal *(NSString *signInEndpoint) { return [self.manager rac_postPath:signInEndpoint parameters:params]; }] map:^NSString *(NSDictionary *response) { return response[@"_links"][@"details"][@"href"]; }] flattenMap:^RACSignal *(NSString *detailsEndpoint) { return [self.manager rac_getPath:detailsEndpoint]; }] replayLast]; ReactiveCocoa to the rescue
60. NSString *services = @"http://example.com/services"; RACSignal *userDetailsSignal = [[[[[[self.manager rac_getPath:services] map:^NSString *(NSDictionary *response) { return response[@"_links"][@"signIn"][@"href"]; }] flattenMap:^RACSignal *(NSString *signInEndpoint) { return [self.manager rac_postPath:signInEndpoint parameters:params]; }] map:^NSString *(NSDictionary *response) { return response[@"_links"][@"details"][@"href"]; }] flattenMap:^RACSignal *(NSString *detailsEndpoint) { return [self.manager rac_getPath:detailsEndpoint]; }] replayLast]; ReactiveCocoa to the rescue
61. http://farm4.staticflickr.com/3007/2655233117_7d5feaa305_o_d.jp This uy is almost definitely an island…
62. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
63. http://www.flickr.com/photos/jakecaptive/3205277810 Forcin lo ic to the server
64. http://www.flickr.com/photos/jakecaptive/3205277810 Forcin lo ic to the server What if you could only use NSDictionary objects for your domain model?
65. landSize : { size: 1440, units: “metres squared” }
66. landSize : { size: 1440, units: “metres squared”, display: “Land size: 1440 m²” }
67. landSize : { size: 1440, units: “metres squared”, display: “Land size: 1440 m²” } Less lo ic in the iOS client!
68. features: { outdoor: [ {garage: 2}, ], indoor: [ “air-conditioning”, “alarm-system”, ... {ensuite: 1} ] }
69. features: [ { label: “Outdoor Features”, features: [ “Garage: 2”, ] }, { label: “Indoor Features”, features: [ “Air Conditioning”, “Alarm System”, ... “Ensuite: 1” ] } ]
70. Mobile API
71. Mobile API
72. Listin API User API Mobile API
73. Listin API User API Mobile API ?
74. Sometimes you need to format data on the client
75. Sometimes you need to format data on the client
77. Could we format beds, baths, carparks using an icon font?
78. propertyFeatures: { display: “\e021 4 \e022 1 \e023 2” } Could we format beds, baths, carparks using an icon font?
79. There and back a ain: an unexpected journey of photo links
80. photo : { thumbnail: ”http://photos.realestate.com.au/100x30/EzMjNhOU”, gallery: ”http://photos.realestate.com.au/320x90/EzMjNhOU”, detail: ”http://photos.realestate.com.au/480x320/EzMjNhOU” } Explicit links for each photo size
81. photo : { thumbnail: ”http://photos.realestate.com.au/100x30/EzMjNhOU”, thumbnail-retina: ”http://photos.realestate.com.au/200x60/EzMjNhOU”, gallery: ”http://photos.realestate.com.au/320x90/EzMjNhOU”, gallery-retina: ”http://photos.realestate.com.au/640x180/EzMjNhOU”, detail: ”http://photos.realestate.com.au/480x320/EzMjNhOU”, detail-retina: ”http://photos.realestate.com.au/960x640/EzMjNhOU” } Explicit links for each photo size
82. photo : { imageServer: ”http://photos.realestate.com.au”, imageId: “EzMjNhOU” } Don’t template the URI in the iOS client
83. photo : { imageServer: ”http://photos.realestate.com.au”, imageId: “EzMjNhOU” } NSInteger width = 100, height = 60; photoUrl = [NSString stringWithFormat: @”%@/%dx%d/%@”, photo.imageServer, width, height, photo.imageId]; Don’t template the URI in the iOS client
84. photo : “http://photos.realestate.com.au/{width}x{height}/EzMjNhOU” Server-side RFC-6570 URI template
85. photo : “http://photos.realestate.com.au/{width}x{height}/EzMjNhOU” CSURITemplate *template = [CSURITemplate URITemplateWithString:photo error:&error]; NSDictionary *params = @{ @"width" : @100, @"height" : @60 }; NSString *photoUrl = [template relativeStringWithVariables:params error:&error]; Server-side RFC-6570 URI template
86. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
87. Keep the app to just the tip of the iceber
88. http://commons.wikimedia.or /wiki/File:Pont_du_Gard_HDR.jp Adopt a standard way of linkin your data
89. Reduce coupling usin hypermedia
90. Web services and REST ›❯ Discoverable iOS APIs ›❯ Simple apps, smart backends ›❯ So where do I start ›❯
91. Thank you Stewart Gleadow @stewgleadow REA Group
92. References John Donne, No Man Is An Island http://en.wikipedia.org/wiki/Meditation_XVII Martin Fowler, Richardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html Leonard Richardson, Justice Will Take Us Millions Of Intricate Moves http://www.crummy.com/writing/speaking/2008-QCon/act3.html Roy Fieldin - REST APIs Must Be Hypertext Driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven Leonard Richardson, API Desi n is Stuck in 2008 http://blog.programmableweb.com/2013/10/07/api-design-is-stuck-in-2008/ Cam Barrie, Desi n your API, Mother %$^ http://vimeo.com/61342270 Mike Kelly, HAL JSON http://stateless.co/hal_specification.html
93. References Perryn Fowler, Richardson Maturity Model By Example http://prezi.com/1-0gtuokjcqo/rmm-by-example/ The Internet En ineerin Task Force (IETF), RFC 6570 - URI Template http://tools.ietf.org/html/rfc6570 Wikipedia, RSDL: RESTful Service Description Lan ua e http://en.wikipedia.org/wiki/RSDL Jim Webber, Savas Parastatidis, Ian Robinson; REST in Practice http://restinpractice.com/book/ Leonard Richardson, Sam Ruby; RESTful Web Services http://shop.oreilly.com/product/9780596529260.do