Build better API clients

BETTER API CLIENTS APIDAYS BERLIN, APRIL 2015 BORIS BÜGLING -
@NEONACHO

COCOAPODS

CONTENTFUL

source: http://appreviewtimes.com

Mobile apps need to be more reliable than the web.

Let's build better API clients to help building better apps

OPEN SOURCE

DOCUMENTATION

/** 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;

COCOAPODS-DOCSTATS $ pod lib docstats 398 tokens, 100.0% documented

TESTING

let expectation = expectationWithDescription("...") waitForExpectationsWithTimeout(10) { (error) in // ...
} expectation.fulfill()

API BLUEPRINT # GET /message + Response 200 (text/plain) Hello
World!

CCLREQUESTREPLAY NSURL *blueprintURL = [[NSBundle mainBundle] URLForResource:@"fitnessfirst" withExtension:@"apib"]; CCLRequestReplayManager *replayManager
= [CCLRequestReplayManager managerFromBlueprintURL:blueprintURL error:nil]; [replayManager replay];

COCOAPODS-COVERAGE pod lib coverage

DISTRIBUTION

"Download the SDK from our webpage."

pod 'ContentfulDeliveryAPI'

COCOAPODS-PACKAGER pod package ContentfulDeliveryAPI.podspec

spec.dependency 'AFNetworking', '>= 2.5.2'

SO, WE'RE DONE, RIGHT?

ANTICIPATING CHANGE IS ONE OF THE CENTRAL THEMES OF REST.

Example: creating a poll

<html> <body> <h1>Poll</h1> <ul> <li><a href="/questions/new" rel="create">Make a new question</a></li>
</ul> </body> </html>

▸ Offers us to create a question ▸ We can
fill in the form we get ▸ Submit the form

We can do the same in our apps with Hypermedia

FORMATS ▸ HAL (application/hal+json) ▸ Siren (application/vnd.siren+json)

SIREN LINK { "entities": [ { "links": [ { "rel":
["self"], "href": "questions/1/choices/1" } ], "rel": ["choices"], "properties": { "choice": "Swift", "votes": 22 } } ] }

SIREN ACTION { "actions": { "create": { "href": "/questions", "method":
"POST", "fields": [ { "name": "question" }, { "name": "choices" } ], "type": "application/x-www-form-urlencoded" } } }

WE CAN NOW CHANGE IMPLEMENTATION DETAILS ON THE FLY

CHANGE URIS OF RESOURCES e.g. /polls/{id} to /questions/{id}

CHANGE HTTP METHODS e.g. PUT to POST

CHANGE THE CONTENT-TYPE

CHANGE FIELDS USED IN FORMS

REPRESENTOR

PRESENCE OF A TRANSITON if let transition = representor.transitions["create"] {
} else { // ... }

ATTRIBUTES OF A TRANSITION if let transition = representor.transitions["create"] {
transition.method transition.uri transition.suggestedContentType }

PERFORMING A TRANSITION request(transition, attributes: [ "question": "Favourite programming language?",
"choices": [ "Swift", "Ruby", "COBOL" ] ])

WHAT HAVE WE LEARNED? ▸ Publish source code! ▸ Document!
▸ Test! ▸ Be robust against change!

THANK YOU!

@NeoNacho boris@contentful.com https://github.com/neonichu http://buegling.com/talks http://www.contentful.com

Build better API clients

Build better API clients

More Decks by Boris Bügling

Other Decks in Programming

Featured

Transcript