Build better API clients

Some thoughts on building better API clients, talk given at APIDays Berlin 2015.

Transcript

1. BETTER API CLIENTS APIDAYS BERLIN, APRIL 2015 BORIS BÜGLING - @NEONACHO
2. COCOAPODS
3. CONTENTFUL
7. source: http://appreviewtimes.com
8. Mobile apps need to be more reliable than the web.
10. Let's build better API clients to help building better apps
11. OPEN SOURCE
13. DOCUMENTATION
14. /** The server address to use for accessing any resources. Default value: "cdn.contentful.com" */ @property (nonatomic) NSString* server; /** Configure a custom user-agent to be used in the HTTP request headers */ @property (nonatomic) NSString* userAgent;
16. COCOAPODS-DOCSTATS $ pod lib docstats 398 tokens, 100.0% documented
17. TESTING
18. let expectation = expectationWithDescription("...") waitForExpectationsWithTimeout(10) { (error) in // ... } expectation.fulfill()
19. API BLUEPRINT # GET /message + Response 200 (text/plain) Hello World!
20. CCLREQUESTREPLAY NSURL *blueprintURL = [[NSBundle mainBundle] URLForResource:@"fitnessfirst" withExtension:@"apib"]; CCLRequestReplayManager *replayManager = [CCLRequestReplayManager managerFromBlueprintURL:blueprintURL error:nil]; [replayManager replay];
22. COCOAPODS-COVERAGE pod lib coverage
23. DISTRIBUTION
24. "Download the SDK from our webpage."
26. pod 'ContentfulDeliveryAPI'
27. COCOAPODS-PACKAGER pod package ContentfulDeliveryAPI.podspec
29. spec.dependency 'AFNetworking', '>= 2.5.2'
30. SO, WE'RE DONE, RIGHT?
31. ANTICIPATING CHANGE IS ONE OF THE CENTRAL THEMES OF REST.
32. Example: creating a poll
33. <html> <body> <h1>Poll</h1> <ul> <li><a href="/questions/new" rel="create">Make a new question</a></li> </ul> </body> </html>
34. ▸ Offers us to create a question ▸ We can fill in the form we get ▸ Submit the form
35. We can do the same in our apps with Hypermedia
36. FORMATS ▸ HAL (application/hal+json) ▸ Siren (application/vnd.siren+json)
37. SIREN LINK { "entities": [ { "links": [ { "rel": ["self"], "href": "questions/1/choices/1" } ], "rel": ["choices"], "properties": { "choice": "Swift", "votes": 22 } } ] }
38. SIREN ACTION { "actions": { "create": { "href": "/questions", "method": "POST", "fields": [ { "name": "question" }, { "name": "choices" } ], "type": "application/x-www-form-urlencoded" } } }
39. WE CAN NOW CHANGE IMPLEMENTATION DETAILS ON THE FLY
40. CHANGE URIS OF RESOURCES e.g. /polls/{id} to /questions/{id}
41. CHANGE HTTP METHODS e.g. PUT to POST
42. CHANGE THE CONTENT-TYPE
43. CHANGE FIELDS USED IN FORMS
44. REPRESENTOR
45. PRESENCE OF A TRANSITON if let transition = representor.transitions["create"] { } else { // ... }
46. ATTRIBUTES OF A TRANSITION if let transition = representor.transitions["create"] { transition.method transition.uri transition.suggestedContentType }
47. PERFORMING A TRANSITION request(transition, attributes: [ "question": "Favourite programming language?", "choices": [ "Swift", "Ruby", "COBOL" ] ])
49. WHAT HAVE WE LEARNED? ▸ Publish source code! ▸ Document! ▸ Test! ▸ Be robust against change!
50. THANK YOU!
51. @NeoNacho boris@contentful.com https://github.com/neonichu http://buegling.com/talks http://www.contentful.com