apis - the pretty face of your microservice

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