Skip to main content

5 more design tips for microservices developers

Considering human needs and tendencies helps make your microservices more valuable to both new and experienced users.
A spoon with lots of little beads in it

Developers spend a great deal of time writing software for consumption by humans—but don't necessarily consider humans in the process. So I started Design4Developers to share practices and patterns for creating better microservices that are simpler to test, write, and deploy at the intersection of science, art, patterns, and methods.

At Red Hat Summit 2021 in June, I presented 10 design tips for microservices developers. The 10 design tips discuss:

  • How to complement your development and deployment efforts with human considerations using the 5 E's (Entice, Enter, Engage, Exit, and Extend) to design compelling microservices experiences
  • How to overlay them with the nine principles of "The SaaS-Ment" to identify typical friction with microservices creation

My previous article shares the first five design tips, and this article outlines the last five. I avoid mentioning any particular technology stack and instead focus on human-centered technology needs. These needs are universal to all humans and transcend any technical choice. Being aware of them will make you a better developer no matter what kind of development you do.

[ Learn more about considering user experience in your architectural design. Read An architect's guide to human-centered design. ]

#6 Sense over summon

I like to ask software developers to consider whether their users are like nuclear power plant operators and airplane pilots. Professions like these require countless hours of training and certification grounded with endless analysis of countless tragic prior events to help prevent repeating terrible past outcomes. These skilled operators keep us safe. Coupled with this training and certification are many hours of validation and testing for the equipment—the plants and planes—these professions use, which are overseen by massive laws, regulations, and standards. In other words, making nuclear plants and airplanes as safe as they are has taken decades of pain and tragedy.

Are your users at this level, or are they new to this task, coming in for the first time maybe even since their training six months ago? Is the task buried in the stream of consciousness surrounding the hundreds of user interfaces they used that day? Do they use this feature once a week, month, quarter, or year? For novice or infrequent users, what are you doing to prevent their needless suffering from toil, friction, and invisible work? What do you give them to help recognize what to do next, rather than trying to figure out from the depths of their memory what you expect them to do? By giving them hints and signifiers for the next action to take, you can enable your users to greatness.

#7 Safety over setback

Providing your users with eject handles and preventing them from doing things that will hurt them—or your systems—is paramount for user success. Providing an error message with no next-best or corrective action is a virtual slap to your user's face. What can you do to minimize the chances of errors in normal use? When users pass in values, do you validate that they are correct? Upon uncovering an error, do you also let them know exactly which field in a long list of passed-in values is incorrect? If you are expecting firstName and they give you fName, do you alert that fName is wrong and they need to use firstName instead? If an error occurs when passing in values, respond with an example of the expected input and give them hints on ranges expected and expectations of those values. If enumerations are used, list them and provide context for when and how to use them.

#8 Stewardship over suffering

As your users gain experience, how do you empower them to become expert users of your service? Do you provide abstractions for groups of common service invocations that streamline use and show specific typical usage patterns? When was the last time you watched users without saying anything and observed their toil, friction, and invisible work? More importantly, once you have uncovered this friction, toil, and invisible work, what are you doing to correct it? When you come back to this system in months or years, your effort to remove those typical user challenges will help your future self (along with your users today). Remember, when your users are invoking your service, they do not have access to the terminal you use while developing it. The microservice you invoke should be a one-stop shop for all information a user needs to discover, learn, use, and correct their interaction with your microservice.

#9 Status over surmising

When deploying and running your microservices at scale, how do you show your users that they are interacting with systems running correctly and safely? Do you show them the service is running successfully and how many successful responses it has served in the last hour, day, or week? Can they ascertain quickly and effectively that the service is up, deployed, and available for requests? If you use a circuit breaker or access token to limit requests, have you clearly documented how it might impact your user? If a circuit breaker is invoked or a key does not allow access, does your user get a clear error message as to what went wrong, or are they left wondering which one of a million things have thwarted their efforts at that time? When providing feedback to your users around errors or status, a "white screen of death" is never OK.

#10 Statistics & study over speculation

When a user finishes interacting with your microservice, what kind of statistics and other meta-information around their interactions and actions do they receive? Do you log the interactions for future study, including looking for patterns of errors, challenges, and of course, successes? Are you periodically and proactively reaching out to your users to see how things are going? Have you asked them for feedback to help you create better user experiences?

[ Thinking about security? Check out this free guide to boosting hybrid cloud security and protecting your business. ]


To implement the 10 design tips for microservices developers, start by ensuring you support new users; they shouldn't have to fumble around until they understand how you wrote the code. Instead, you want them to quickly understand your service without having to think too deeply into how to make it work for them. It is unfair to expect them to summon deep-seated knowledge about the code, tribal knowledge, past training, and incomplete and incoherent documentation.

Next, they need escape hatches, back buttons, and ways to back out of something if they need to. As they engage in your service over time, give them insights and curate experiences to reward them for investing in the offering. Provide them with status information about what they are doing and prevent "white screens of death" when they make mistakes.

Finally, spend time collecting real feedback from your users. Ensure you understand their needs and are not wishing they are something they are not.

By using these 10 tips, you will create better and more engaging microservices. You can watch my presentation by logging in to the Red Hat Summit 2021 website. In my next article, I will overlay these 10 tips with the 5 E's (Entice, Enter, Engage, Exit, and Extend) to help make your microservices better for your users.

Author’s photo

Jim Tyrrell

Jim Tyrrell founded Design 4 Developers an Open Community that targets the intersection of Design and Software Development.  He is a 25 year Java veteran and holds a Masters of Design Methods degree from the Illinois Institute of Technolo More about me

Navigate the shifting technology landscape. Read An architect's guide to multicloud infrastructure.


Privacy Statement