Yaas.io is a marketplace for microservices. These nine user experience guidelines will make your APIs better than ever before.

1. APIs
THE PRETTY
FACE OF YOUR
MICROSERVICE
Andrea Stubbe
Product Lead YaaS.io, SAP Hybris
@andreastubbe

2. YAAS.IO IS A MARKETPLACE
FOR MICROSERVICES, EACH
HAVING AN API

3. PROTO-PERSONAPROTO-PERSONA
LIKES NEW STUFF.
BECAUSE IT’S NEW
WANTS TO TRY IT
OUT, NOW! IN
THE MIDDLE OF
THE NIGHT.
HAS HIS OWN
IDEAS.
WANTS TO BUILD,
NOT ONLY CONSUME.
DO IT FIRST, READ
THE MANUAL LATER,
INVENT SOMETHING
ON THE WAY.

4. WHY IS GOOD UX IMPORTANT TO US
THE NEXT API IS JUST
A CLICK AWAY!
IF YOU LIKE IT, YOU
TALK ABOUT IT
FUNCTIONALITY
SECURITY,
PERFORMANCE – IT’S
ALL THERE
THE FIRST
IMPRESSION COUNTS
DO IT FIRST, READ
THE MANUAL LATER,
INVENT SOMETHING
ON THE WAY.
WANTS TO TRY IT
OUT, NOW! IN THE
MIDDLE OF THE
NIGHT

5. LOOK AT APIs AS A
USER INTERFACE

6. API
THIS IS A USER INTERFACE

7. APPLY THESE NINE USER
EXPERIENCE GUIDELINES TO
MAKE YOUR APIS BETTER
THAN EVER BEFORE!

8. #1 START WITH A REALLY GOOD IDEA
A FANCY API
WON’T RESCUE
A USELESS
MICROSERVICE
DON’T BE
AFRAID TO
THROW THINGS
AWAY

9. #2 MATCH YOUR SYSTEM TO THE REAL
WORLD
EVERYBODY
KNOWS THE
REAL WORLD
USE CONCEPTS
THEY CAN
RELATE TO
USE METHAPHORS
WHEN THERE’S NO
REPRESENTATION IN
THE WORLD
APPLY DOMAIN
DRIVEN DESIGN

10. #3 DON’T REINVENT THE WHEEL
FOLLOW DE-
FACTO
STANDARDS
FAMILIAR IS
BETTER THAN
ELEGANT
SHARE
PATTERNS,
TRAITS AND
SHEMAS

11. #4 INTERNAL CONSISTENCY
THE SAME
ACTION SHOULD
WORK THE SAME
WAY. ALWAYS.
USE
CONSISTENT
ERROR CODES
AND MESSAGES
HAVE NAMING
GUIDELINES
USE A PATTERN
LIBRARY

12. #5 BREAK THE RULES
WHEN REST AND
USABILITY
DISAGREE, CHOOSE
USABILITY
BREAK RULES
ONLY AFTER
YOU MASTERED
THEM
BREAK RULES
CONSISTENTLY

13. #6 HELP AND DOCUMENTATION
ENSURE REALITY IS
THE SAME AS THE
DOCUMENTATION
MAKE PEOPLE
READ YOUR
DOCUMENTATION
USE CORRECT
RESPONSE CODES
ERROR MESSAGES
EXPLAIN HOW TO
RECOVER

14. #7 PREVENT ERRORS
MAKE IT VERY
HARD TO MAKE
MISTAKES
CLEARLY STATE
WHAT IS
REQUIRED
PUT VALIDATION
RULES IN THE API
DEFNITION
BE TOLERANT
WHEN READING
INPUT

15. #8 MINIMALIST DESIGN
LESS IS MORE.
DON’T OVERLOAD
THE API
ONLY ASK FOR
DATA THAT IS
REALLY NEEDED
AVOID
REDUNDANCIES
USE REFERENCES
INSTEAD OF THE
FULL DATA SET

16. #9 NEVER JUSTIFY YOUR DESIGN
IF YOUR USERS
DON’T LIKE IT, THEY
WON’T USE IT.
IF THEY DON’T
USE IT, YOUR API
FAILED
DEFINE YOUR API
TOGETHER WITH ITS
CONSUMERS

17. HOW TO MAKE YOUR APIS PRETTY
#1 START WITH A REALLY GOOD IDEA
#2 MATCH YOUR SYSTEM TO THE REAL WORLD
#3 DON’T REINVENT THE WHEEL
#4 INTERNAL CONSISTENCY
#5 BREAK THE RULES
#6 HELP AND DOCUMENTATION
#7 PREVENT ERRORS
#8 MINIMALIST DESIGN
#9 DON’T JUSTIFY YOUR DESIGN

18. THESE NINE USER EXPERIENCE
GUIDELINES WILL MAKE YOUR APIS
BETTER THAN EVER BEFORE
IF YOU TAKE CARE THEY ARE
UNDERSTOOD AND LIKED

19. YAAS.IO