One of the common Web API design anti-patterns that I see in the field is the exposure of database model in the API contract. If you are building a Java Spring Boot JPA application then it means exposing JPA entities as Web API’s request and response objects. The primary reason this happens is because most teams are not following contract first model of API design. They start from code and database schema and then they create API contract from them.
This is not the first time I have seen this anti-pattern being applied by development teams. I have seen this often so I thought let me document it so that in future I can share this post. The advantages of document such lessons/patterns/practices are:
- I can be thorough in my explanation. Writing helps me understand if my point is valid. Writing is thinking for me.
- While explaining to a developer I might forget a key point.
- Give the development team time to reflect upon the feedback by themselves.
- Discussion after going over the post might be more productive.
- I can keep updating this post.
Following are the reasons that I think we should avoid exposing database model as an API contract.
Continue reading “Web API Design Anti-Pattern: Exposing your database model”
Once again, I stumbled upon the documenting architecture decisions post by Michael Nygard. This time, a particular line from his post got me thinking and made me dig a little deeper into the subject. The line said, “ ‘architecturally significant’ decisions [are] those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.” The reason this piece of statement is important is because most of the time architects are not clear about what they should document.
The author suggests that we must document architecturally significant decisions. He divides them into five categories. In the post, he does not give examples against those categories, so, I am taking the liberty to add mine.
Continue reading “Architecturally Significant Decisions”
Below is my interpretation of these categories. It could be different from the author’s intent.
Below is the template that I use to document software architecture. This is based on the experience I gained doing architecture and design work over the years.
If you prefer Google Docs then you can create a copy of the template. If you prefer Markdown version then you get it from the Github repository.
Continue reading “Software Architecture Document Template”
These days we all are told to build stateless applications. Stateless apps are those that don’t store any state in the application process and fetch any state from a centralised datastore (it could be a global cache or a database). The sixth factor in 12 factor app also talk about the same principle.
Execute the app as one or more stateless processes
Twelve-factor processes are stateless and share-nothing. Any data that needs to persist must be stored in a stateful backing service, typically a database.
There are advantages in building stateless applications primary being ability to scale horizontally with ease. When we build stateless applications we push the scalability problem to the database. We expect our database to scale horizontally. This usually is solved by sticking a global cache (Redis or Memcached) in between. Scaling cache is relatively easy and solved problem. Keeping cache updated with updates is a hard problem. We will discuss it some other time.
Continue reading “4 Reasons You Might Want To Build Stateful Apps”
I have worked with multiple software development teams that because of feature delivery pressure does not apply best practices. This later leads to tech debt and cost more time. In the last project team that I helped they made two small mistakes:
- They didn’t use pagination in the collection resources. They were fetching the list of data from the database and returning back to the user as JSON. During development when data was small they didn’t face any issues. But, later when customer started doing testing it became a monumental task to add pagination in all the collection resources.
- They were returning domain entities in the response. This meant they were transferring more data over the wire than it was necessary.
So, they were breaking two best practices:
- Using pagination for collection resources
- Keep your domain object different from representation object
Continue reading “Using ArchUnit To Enforce Architecture Best Practices”
I love the idea of everything as code. It enables use of version control for all aspects of software development. These days we use everything as code approach for documentation, infrastructure provisioning, deployment automation, continuous integration build jobs, pull request and issue templates, and many other things. The beauty of this approach is that it enables us to use the same tools as we use use for software development.
One aspect of the software development where we are lacking the as code approach is in creating architecture diagrams.
Continue reading “Software Architecture Diagrams as Code”
All software has software architecture. This is true even when a team has not spent time coming up with it. This architecture is often called Big ball of Mud. A big ball of mud architecture is a software system that lacks a perceivable architecture.
Every software system has a software architecture is similar to saying not taking a decision is also a decision.
Continue reading “Architecture Hoisting”
Today, I read a paper titled Lessons from Giant-Scale Services. This paper is written by Eric Brewer, the guy behind CAP theorem. It is an old paper published in 2001. The paper helps the reader build mental model on how to think about availability of large scale distributed systems.
Continue reading “Paper Summary: Lessons from Giant-Scale Services”