your api is a ui
TRANSCRIPT
![Page 1: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/1.jpg)
Your API is a UIChristopher Hoult
![Page 2: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/2.jpg)
Your API is a UI @choult
Who is this guy?
“We’re Hiring”
Previously...
![Page 3: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/3.jpg)
I also act
Credit: Richard Brown
![Page 5: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/5.jpg)
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
![Page 6: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/6.jpg)
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
![Page 8: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/8.jpg)
Your API is a UI @choult
Who are your users?
• Developers• Colleagues• Customers• Their Customers• Applications
![Page 9: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/9.jpg)
Your API is a UI @choult
What does your API do?
• Real use cases• User stories• Document usage/flow• Sell your API
![Page 10: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/10.jpg)
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
![Page 11: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/11.jpg)
Your API is a UI @choult
API Hierarchy of Needs
APIUX.com: http://bit.ly/Zl8Exo
![Page 13: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/13.jpg)
Your API is a UI @choult
Consistency
• Improves comfort for user• Style guide (PSR-1/2; REST etc.)• Common attributes/functions• Naming• Error codes
![Page 14: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/14.jpg)
Your API is a UI @choult
Patterns
• Users understand Patterns• Patterns aid understanding• Webservices: RPC, REST• Code: Gang of Four etc.
![Page 15: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/15.jpg)
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
![Page 16: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/16.jpg)
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
![Page 17: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/17.jpg)
Your API is a UI @choult
Simplicity
• Best result of abstraction• More straightforward, more use• Smaller footprint = fewer failure paths• Easy fault detection
![Page 18: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/18.jpg)
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!
![Page 20: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/20.jpg)
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
![Page 21: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/21.jpg)
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
![Page 22: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/22.jpg)
![Page 23: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/23.jpg)
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
![Page 24: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/24.jpg)
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
![Page 25: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/25.jpg)
Your API is a UI @choult
Feedback
• Clear feedback
• Reasons for failure
• Appropriate language
• Error codes• Normalized; human readable• Provide glossary
![Page 27: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/27.jpg)
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
![Page 28: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/28.jpg)
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
![Page 29: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/29.jpg)
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
![Page 31: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/31.jpg)
Your API is a UI @choult
<Inspirational Title>
• Flexibility• Extensibility• Serendipity• Outreach• Encouragement
![Page 33: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/33.jpg)
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
![Page 35: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/35.jpg)
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!
![Page 37: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/37.jpg)
Your API is a UI @choult
Thank you!@[email protected]@
This presentation was typeset in HandTIMES and Open Sans, using Adobe InDesign CS6 (because I’m a lunatic)
Feedback please! https://joind.in/13392
![Page 38: Your API is a UI](https://reader035.vdocuments.mx/reader035/viewer/2022062406/55a83b7b1a28abff768b4863/html5/thumbnails/38.jpg)
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