Your API is a UI

Your API is a UIChristopher Hoult

Your API is a UI @choult

Who is this guy?

“We’re Hiring”

Previously...

I also act

Credit: Richard Brown

YMMV

http://bit.ly/1yvvYb5

Your API is a UI @choult

What is a UI?

A “space where interactions between humans and machines occur. The goal of this interaction is effective operation and control of the machine on the user’s end, and feedback from the machine, which aids the operator in making operational decisions.”

Wikipedia

Your API is a UI @choult

What is an API?

“An application programming interface (API) specifies a software component in terms of its operations, their inputs and outputs and underlying types. Its main purpose is to define a set of functionalities that are independent of their respective implementation, allowing both definition and implementation to vary without compromising each other.”

Wikipedia

Users

http://bit.ly/1DMivvR

Your API is a UI @choult

Who are your users?

• Developers• Colleagues• Customers• Their Customers• Applications

Your API is a UI @choult

What does your API do?

• Real use cases• User stories• Document usage/flow• Sell your API

Your API is a UI @choult

What can users do?

• Why are you exposing an API?• It’s very rare to expose everything• Too much complexity -> confusion• Define restrictions• Validate user stories against goals

Your API is a UI @choult

API Hierarchy of Needs

APIUX.com: http://bit.ly/Zl8Exo

Usability

http://bit.ly/1DWUcva

Your API is a UI @choult

Consistency

• Improves comfort for user• Style guide (PSR-1/2; REST etc.)• Common attributes/functions• Naming• Error codes

Your API is a UI @choult

Patterns

• Users understand Patterns• Patterns aid understanding• Webservices: RPC, REST• Code: Gang of Four etc.

Your API is a UI @choult

Information Hierarchy

• Define ERM• Arrange entry points from user POV• Nesting entities can be problematic • Get it right: classes and objects intuitive

Your API is a UI @choult

Abstraction

• User stories guide API design• Hide complexity• Avoid adhering to underlying model• Do the hard work so users don’t have to

Your API is a UI @choult

Simplicity

• Best result of abstraction• More straightforward, more use• Smaller footprint = fewer failure paths• Easy fault detection

Your API is a UI @choult

Extensibility

• Flipside to abstraction• How will users extend codebase?• Restrict as required - public/protected/private

• Take care - hard to retract public• Patterns help here!

Functionality & Reliability

http://bit.ly/109m7bG

(Oh, so he does do colour!)

Your API is a UI @choult

Testing

• Use appropriate testing methodology• Make part of build/release process• Monitor production with live testing• Consider record/replay testing• Regression testing

Your API is a UI @choult

Metrics

• Metrics tell you what is happening• Record status codes• Calibrate with normal running• Insight into running code• Graphite/statsd

Your API is a UI @choult

Logging

• Tells you what happened• Helps debug production faults• Reference in error messages• Insight into running applications• Information for users of code

Your API is a UI @choult

Versioning

• Plan versioning upfront• Define upgrade/deprecation strategy

• What is a breaking change?• How long will API be supported?

• Communicate with users

Your API is a UI @choult

Feedback

• Clear feedback

• Reasons for failure

• Appropriate language

• Error codes• Normalized; human readable• Provide glossary

Proficiency

http://bit.ly/1rJmLHJ

Your API is a UI @choult

Documentation

• No such thing as “self-documenting code”• Write fulsome documentation• Include working examples• Cross-link from code• Manuals, Quick Start Guides, Cookbooks

Your API is a UI @choult

Living Documentation

• Docblocks (Javadoc/PHPdoc) are a good start

• Cross-language (eg Doxygen)• Use standards like PSR 5• Annotations• Interactive documentation - eg. IODocs

Your API is a UI @choult

Support / Community

• Define channels of communication• Define location for participation• Invite feedback• Invite contribution - define guidelines• Respond gracefully and attentively• Learn from your users

Creativity

http://bit.ly/109m7bG

Your API is a UI @choult

<Inspirational Title>

• Flexibility• Extensibility• Serendipity• Outreach• Encouragement

Pragmatism

http://bit.ly/1votyWc

Your API is a UI @choult

On Pragmatism

• Pragmatism is good!• Can promote technical debt• Find a balance - RESTlike, RPCish• Be realistic• Iterate - versioning and deprecation

Take Pride

http://bit.ly/1xCeQ1W

Your API is a UI @choult

Your API is You!

• Like your UI, your API is your public face• It is your avatar• Take pride in your work• Impress your users with its awesomeness!

Questions?

http://bit.ly/1npSVI6

Your API is a UI @choult

Thank you!@choultchristopherhoultchris@choult.com@

This presentation was typeset in HandTIMES and Open Sans, using Adobe InDesign CS6 (because I’m a lunatic)

Feedback please! https://joind.in/13392

Your API is a UI @choult

Resources / Inspiration

10 User Interface Design Fundamentals - Kyle Sollenbergerhttp://blog.teamtreehouse.com/10-user-interface-design-fundamentals

APIUX: API Hierarchy of Needshttp://apiux.com/2013/05/29/api-hierarchy-needs/

5 Golden Rules for Great Web API Design - Jordan Ambrahttp://www.toptal.com/api-developers/5-golden-rules-for-designing-a-great-web-api