apis - the pretty face of your microservice
TRANSCRIPT
APIsTHE PRETTY FACE OF YOUR MICROSERVICEAndrea StubbeProduct Lead YaaS.io, SAP Hybris
@andreastubbe
YAAS.IO IS A MARKETPLACE FOR MICROSERVICES, EACH HAVING AN API
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.
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
LOOK AT APIs AS A USER INTERFACE
APITHIS IS A USER INTERFACE
APPLY THESE NINE USER EXPERIENCE GUIDELINES TO MAKE YOUR APIS BETTER THAN EVER BEFORE!
#1 START WITH A REALLY GOOD IDEA
A FANCY API WON’T RESCUE
A USELESS MICROSERVICE
DON’T BE AFRAID TO THROW THINGS AWAY
#2 MATCH YOUR SYSTEM TO THE REALWORLD
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
#3 DON’T REINVENT THE WHEEL
FOLLOW DE-FACTO
STANDARDS
FAMILIAR IS BETTER THAN ELEGANT
SHARE PATTERNS, TRAITS AND SHEMAS
#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
#5 BREAK THE RULES
WHEN REST AND USABILITY
DISAGREE, CHOOSE USABILITY
BREAK RULES ONLY AFTER YOU MASTERED THEM
BREAK RULES CONSISTENTLY
#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
#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
#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
#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
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
THESE NINE USER EXPERIENCE GUIDELINES WILL MAKE YOUR APIS BETTER THAN EVER BEFOREIF YOU TAKE CARE THEY ARE UNDERSTOOD AND LIKED
YAAS.IO