Service Design Best Practices - Part II

Sameh Muhammed - Oct 15 '22 - - Dev Community

Introduction

By now most softwares separating the server side logic from user interface logic by developing a back end web services, and make them accessible over the network to consumers either web applications or mobile applications or even another back end services, so developing a maintainable and reliable back end service is essential to deliver a good software, here we will discuss a bunch of best practices you should consider when you developing your back end service.

You can find Part one Service Design Best Practices - Part I

Controllers Are For Delegation Only

Try as much as possible to not include any business logic or validations inside your Controllers, the controller is for firing the right action only, while you are processing you can do what ever you want.

Use API Documentation

Using API documentation saves a lot of time for you and prevent a lot of interruption, and there are now multiple tools and frameworks that automatically generates the documentation directly from your code (OpenAPI or Swagger), so you will not bother yourself to update the documentation whenever you update the code, it also gives anyone the ability to test and deal with APIs directly.

Make Your Service Portable

While you are developing the service, you may put custom configuration or code snippets that just work in specific environment, and if you tried to run it in any other machine it will fails, which makes onboarding new members or moving the service from one machine to another painful, so you should mock your dependencies or 3rd parties you deal with to make your service testable and runnable easily, or you can provide container version that includes your service and its' dependencies as docker compose file so that any new member can run the service anywhere and get the feel of how it behaves.

Isolate Service Dependencies Integration Logic

Any service to achieve its' goal needs to integrate with other systems or services (Database, another BE service, Queuing service..), and mixing your business logic with the integration code reduces your code quality and makes maintenance activities and debugging harder, so you should consider hiding the integration logic behind Anti-Corruption layer.

Anti-Corruption Layer

Don't Retrieve All Records

While working with GET APIs you should always consider using pagination and filtration to avoid get all the data from your DB, this will save for you a lot of performance, resources and make your service scalable.

Don't Block Your Consumers

At some certain cases you may need to do some heavy logic that may take a while to be done, at that certain cases you should not block your consumer until you finish, instead you can release the connection and send back to consumer an identifier so he can poll the operation result with this identifier or provide a notification service that notifies him after the processing finished.

Put Resilience Into Your Consideration

Most of service run over the network and deals with other services also over the network, and working over networks not like calling another method inside your service or your class, instead this calling have a lot of requirements, it takes more time, it moves around multiple network devices to get your result, it's unreliable and not predictable, so you should make this into your consideration while working with networks, consider request timeouts, fallbacks, heavy traffic and service unavailability, you should handle all that cases.

It's Not Only HTTP

HTTP has been proven itself and it's capabilities over time and it's evolve over time, and of course like anything in this world, it has its' pitfalls and cons, fortunately, it's not your sole option, there is WebSocket and Messaging, try to know about all your options and what is best use case for each one.

Resources

IF YOU LIKED THE POST, THEN YOU CAN SUPPPORT SUCH CONTENT WITH A CUP OF COFFEE, THANKS IN ADVANCE.

Buy Me A Coffee

. . . . . . . . . . . . . . . . . . . . . . . . . . . .