Please download the deck to read the accompanying notes pinned to the lower right of each slide.
As organizations become more savvy and increase the amount of data available through APIs, they must pay more attention to the UX of their data customers. Thankfully they no longer post an Excel file and call that "open data" - they have developer portals, documentation in Swagger, and feedback channels. But that leads to many opportunities to improve the human2human as they enable the machine2machine. Learn where your UX skills are needed to improve next generation of the open data revolution.
10 Minutes – make it valuable
I am…
Product owner
Open Data & APIs
Champion of UX Best Practices
If you go to stuartridgway.com you can read about all of this
What is Open Data?
Organizations make their data and information available to developers
Free
Pay to play
Get paid
Aligned with organization’s mission
** APIs for sharing their data from machine to machine
The way the Internet works
You never know you’re viewing data and information from multiple sources
For our purposes today
Your goal (as the UX professional advising the product owner) is to provide a happy user experience for software developers and engineers
You and your organization want developers to use the APIs because
It makes the organization money
It “markets” the organization’s brand and content
Extends the organization’s reach
Not much on UX for APIs
This is the opportunity for you to work with ogranizations on Open Data UX:
Yes, there are two “paths” you can go by
The APIs
The documentation
===========================
The APIs that the software engineers are working with should provide a positive UX
Even though the APIs are used for machines to talk to one another, software engineers (humans) still need to set up the connections to make them work.
The documentation that accompanies the API must also provide a positive UX
Common sense Web UX applies
But API documentation has its own specific use cases
Developers are usually the ones who write the documentation!
Customer (software engineer) perspective
So let’s walk through an example
I have an AWESOME idea for an app
I’m not going to ask you all to sign NDAs but PLEASE do not share this.
Really, this is my kids’ college fund in the making.
Ready?
Kittinder.
An app for setting up play dates for your cat
Brilliant right?
Dog play dates are easy
They do some sniffing, they woof, they’re good
Cats are very finicky
If you want to find them a playdate, you have to make sure you get the right match
Three Sources of data
PetCensus
Like US Cesus that has information about your household, your education, you employment, PetCensus captures cat statistics across the country. This way I can easily find what actual cats are nearby so I know what my play-dating pool is.
The ASPCE (American Society for Promoting Cat Emotions)
Has information about the nature of each breed of cat. Siamese are moody, calicoes are coy. What other dimensions might they have? How do they interact? We’ll see.
Tinder
Once I get the various dimensions of each breed, half-breed and alley cat, I now need to figure out how to match them. Tinder publishes its matching algorithm as an API. I send them the weighted dimensions and they send me back a score.
As I walk you through trying to access the data from these three sources, think about the different aspects of my user experience.
Interactive Design (ID)
Information Architecture (IA)
Visual Design (VD)
Usability (U)
Communication (C)
Path 1: Documentation for the APIs
PetCensus
Remember: Developers are people too.
“You” are the UX professional representing the organization publishing the APIs
You want to hook them in
If it’s too hard, developers give up and go elsewhere
The basics apply
Developer have specific use cases
American Society for the Promotion of Cat Emotions
Organize the pages consistently
Group API documentation logically within your menu / navigation
If there are different ways to work with a particular data set, group them together
Group similar actions like POST and GET
Organize information on pages consistently
Background
What the Data Is
Ideas for Using it
Resource URL
Different fonts for code
Manage with CSS so its 508 compliant
Search Parameters
Methods
Use standard taxonomies
Use standard taxonomies (ISO cat breeds)
When searching across APIs from different organizations I want to be able to use consistent terms
Link to those taxonomies if you don’t own them so I don’t have to figure them out (ID)
Examples
Clickable Examples
Continuing from above…
Return Values
What the developer should expect with the results
Grouping by source
Limited number of results
Pull request at the bottom of each documentation page (U)
If published in OpenSource repository like GitHub
Let developers help you and other developers
Open data begets collaborative efforts
Common Sense
Change log
News / Announcements
Contact Us
API Keys
What’s the process…
Make the API Key request process painless
Be clear about what it entails
Personalize the API key email
Make developers feel welcome
There are few chances to interact with your human customer
Path 2: The APIs Themselves
PetCensus “count” API
Making Data Requests
Create useful methods / calls
Make it easy to get the number and type of cats in a particular zip code
Standardize the query requirements
A developer should be able to figure out how to do a new query based on what s/he learned making other queries
Developers begin to lose interest fast if they can’t begin using your API right now
Package and deliver the data nicely
Use JSON (IA)
JavaScript Object Notation
This has become the standard for most data sharing over the Web
XML is on its way out because its not as light as JSON
Data vs. Metadata
Static data (what the source is, metadata, etc.) should be separate from dynamic data content (VD)
Consistent results
Use taxonomies consistently
Organize return values
Conform data types
All weights include pounds and ounces even if ounces = 0
Provide guidance in error codes
Help product owners create a happy user experience for your developers
Jump in early and push
Influence the product owner
It will make or break the project’s success
Different people have a stake in the UX of an API
Data stewards
Your developers
Documentation writers and designers
3rd party developers who who build tools off of your own APIs
They use APIs/documentation and provide feedback
Their customers
AND Different data customers have different needs
Before I say goodbye…
Every time you and your users connect you have an opportunity to change and improve
Iterate - Constant opportunities for improvement
Metrics / Usage
Hackathons = Usability Test
Invite me to come beat on your senior leaders
stuartridgway.com
stuart1@pyramidmusic.com