Post on 18-Jul-2015
Approaching APIs
Ross Singer HydraHack13th January 2015
Considerations before you even start whiteboarding your API
ScopeHTTP/Web based APIs
Don’t use SOAP
SOAP
The End.
ScopeHTTP/Web based APIs
• REST
• RPC (XML, JSON)
• Hybrid
• Web hooks
• SOAP
• etc.
Important noteNobody is an expert at designing APIs
But eventually you can fail enough to consider yourself “experienced”
The origin story for every API ever
Product Manager
“We need Product A™ to update Product B™ when a user
does XYZ®”
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.”
“That should be all we need.”
It’s easy to underestimate the importance of your
API
An API is first and foremost a commitment
Even for simple, internal-only APIs
A couple of safe assumptions
Assume your API will outgrow your original use
caseAt the same time, you don’t want to over engineer for a
million unrealized possibilities
Assume you’ll eventually paint yourself into a corner and you’ll need to redesign
• 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
e.g. Google
e.g. Facebook
That said,you’re probably not Google or Facebook
Your API is a commitment to change management
Competing interests• Functionality
• Simplicity
• Security
• Performance
• Scalability
• Maintainability
• Durability
• Extensibility
• Usability
• Understandability
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?
Adding is good changeas long as it’s non-breaking
Releaser’s remorseThe day after your API goes live, you’ll think of a much
better way you could have implemented it
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?
Minimize risk by designing less yourself
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
“De facto” standardse.g. Lucene query syntax,
AWS S3 API
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
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?
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?
Tools
• API design/documentation services• apiary.io• Mashape
• API management services• Mashery• apigee• 3Scale
Change is inevitable
Prepare for it and avoid the preventable
Cheaper to invest in it early
@talisfacebook.com/talisgroup
+44 (0) 121 374 2740
talis.cominfo@talis.com
48 Frederick StreetBirminghamB1 4HN