approaching apis

41
Approaching APIs Ross Singer HydraHack 13th January 2015 Considerations before you even start whiteboarding your API

Upload: ross-singer

Post on 18-Jul-2015

77 views

Category:

Technology


0 download

TRANSCRIPT

Page 1: Approaching APIs

Approaching APIs

Ross Singer HydraHack13th January 2015

Considerations before you even start whiteboarding your API

Page 2: Approaching APIs

ScopeHTTP/Web based APIs

Page 3: Approaching APIs

Don’t use SOAP

SOAP

Page 4: Approaching APIs

The End.

Page 5: Approaching APIs

ScopeHTTP/Web based APIs

Page 6: Approaching APIs

• REST

• RPC (XML, JSON)

• Hybrid

• Web hooks

• SOAP

• etc.

Page 7: Approaching APIs

Important noteNobody is an expert at designing APIs

Page 8: Approaching APIs

But eventually you can fail enough to consider yourself “experienced”

Page 9: Approaching APIs

The origin story for every API ever

Page 10: Approaching APIs

Product Manager

“We need Product A™ to update Product B™ when a user

does XYZ®”

Page 11: Approaching APIs

Developer

“I made a noddy little endpoint in Product B to POST a JSON serialization of a FOO object from Product A, turn it

into a Product B BAR, and save it.”

Page 12: Approaching APIs

“That should be all we need.”

Page 13: Approaching APIs

It’s easy to underestimate the importance of your

API

Page 14: Approaching APIs

An API is first and foremost a commitment

Page 15: Approaching APIs

Even for simple, internal-only APIs

Page 16: Approaching APIs

A couple of safe assumptions

Page 17: Approaching APIs

Assume your API will outgrow your original use

caseAt the same time, you don’t want to over engineer for a

million unrealized possibilities

Page 18: Approaching APIs

Assume you’ll eventually paint yourself into a corner and you’ll need to redesign

Page 19: Approaching APIs

• New functionality in your app may radically affect your API

• Changes in client expectations

• A new outlook on what your application’s actual product is

Page 20: Approaching APIs

e.g. Google

Page 21: Approaching APIs

e.g. Facebook

Page 22: Approaching APIs

That said,you’re probably not Google or Facebook

Page 23: Approaching APIs

Your API is a commitment to change management

Page 24: Approaching APIs

Competing interests• Functionality

• Simplicity

• Security

• Performance

• Scalability

• Maintainability

• Durability

• Extensibility

• Usability

• Understandability

Page 25: Approaching APIs

Changes are expensive

• Even internal APIs are going to require refactoring in at least 2 places

• Product & sales aren’t interested in your ideas about improving the API

• How do you communicate changes to your users?• How do you deal with their pushback?

Page 26: Approaching APIs

Adding is good changeas long as it’s non-breaking

Page 27: Approaching APIs

Releaser’s remorseThe day after your API goes live, you’ll think of a much

better way you could have implemented it

Page 28: Approaching APIs

Versioning• Technical

• Lots of options!• routes

• POST /v2/foo/bar• headers

• GET /foo/barVersion: 2

• parameters• GET /foo/bar?version=2

• All of them have downsides!• Policy

• How to maintain/support older versions?• How to deprecate/shut down?• What have you obligated yourself to in Ts&Cs?

Page 29: Approaching APIs

Minimize risk by designing less yourself

Page 30: Approaching APIs

Use standards where possible

• Eliminates the need to think of every possibility upfront

• Probably already a community of practice to build upon

• More upfront investment than rolling your own• May seem limiting• May, in fact, be limiting• Likely has unforeseen advantages

• Fewer long-term costs

Page 31: Approaching APIs

“De facto” standardse.g. Lucene query syntax,

AWS S3 API

Page 32: Approaching APIs

Use your API!

• If the API is your access point, it’s far less likely to get neglected

• Internal use gives a chance to refine it before wider release

Page 33: Approaching APIs

Testing your API• Unit tests

• Integration tests:• Test exactly how your users will call your API

• All functions, all versions• Test the limits: invalid inputs, unauthorized access, flow control, etc.

• Stress testing• What happens under load?

• To the API?• To the application as a whole?

• Where are the bottlenecks? What is their impact?

Page 34: Approaching APIs

Security• Important from the outset!

• Whitelists/security groups get outgrown quickly

• What are your roles/privileges?• How do you identify them?• How do you ensure clients only can access what they

are supposed to?

• How much information do you reveal in your error responses?

Page 35: Approaching APIs

Tools

• API design/documentation services• apiary.io• Mashape

• API management services• Mashery• apigee• 3Scale

Page 37: Approaching APIs

Change is inevitable

Page 38: Approaching APIs

Prepare for it and avoid the preventable

Cheaper to invest in it early

Page 39: Approaching APIs

http://www.talis.com/jobs/

We’re hiring!

Page 40: Approaching APIs

We have internships, too

http://www.talis.com/internships/

Page 41: Approaching APIs

@talisfacebook.com/talisgroup

+44 (0) 121 374 2740

[email protected]

48 Frederick StreetBirminghamB1 4HN