Author Archives: Roland Nimako

REST API Design.

The Stack Overflow Blog post “Best practices for REST API design” caught my eye (March 2, 2020). Blog for Stack Overflow. The article explains what a REST API is and why it’s important to design it correctly. It then gives specific advice, like accepting and responding in JSON, making sure that endpoint paths are made up of nouns instead of verbs, using plural nouns for collections, allowing filtering, sorting, and panning, handling errors correctly, creating versions of your API, using standard HTTP status codes, and enforcing security and caching. The main idea is that APIs should be easy to understand, reliable, adaptable to the future, and simple for other coders to use.

As I learn more about financial systems, data analytics, and making tools that can reveal or use services, I need to know how to build and use backend components in a clean way. The piece caught my attention because it is both theoretical and useful, and it is written in a clear way that connects what developers expect now with what is best practice. Because the business systems I work on in the future might use APIs to connect billing, collection, or data analysis tools, this kind of advice seems very useful.

I felt a lot of things reading this. First, I liked how the focus was on using resources (nouns) instead of verbs in URL paths. This is something I have seen broken in older systems (for example, /getUserDetails or /updateBillingInfo), which shows right away that the design isn’t clear. “Use nouns instead of verbs in endpoint paths,” the paper says. Blog for Stack Overflow. This idea makes things clearer: when I make or use an API, I want to be able to look at endpoints and immediately understand what the system models (users, orders, and invoices), not what action is being taken. In REST, the action is taken care of by the HTTP verb.

Another thing is that the article talks about standard error codes, versioning, filtering, sorting, and pagination. These are important for growth and maintainability but are often forgotten when speed is the most important thing. When I build an API for a payment module today without planning for versioning, for example, clients may not work with future changes (like adding new fields or changing the way things work), which causes problems between teams.

Basically, I learned or reinforced the idea that designing an API isn’t just about “making something that works.” It’s also about making something that other developers can use easily and that can grow. This fits with one of my user goals, which is to be correct and organized with systems, documentation, and interfaces. A well-designed API makes things clearer, cuts down on mistakes, and allows for future growth, which is a lot like how I focus on detailed paperwork and efficient financial systems.

ReferenceStack Overflow Blog. (March 2, 2020). The best ways to build a REST API. https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/

From the blog Site Title by Roland Nimako and used with permission of the author. All other rights reserved by the author.

Design Pattern

Design patterns are an important part of the course, but I have only touched on them briefly so far. This piece is a clear and easy-to-understand introduction to them. To connect theory and practice, I thought the article’s way of explaining what design patterns are, why they’re important, and how they’re grouped would be perfect. This is because I’m learning how to code and thinking analytically about how software is built and designed. Using my skills in finance and data analysis to look at software systems in a more structured and planned way also fits with this goal. 

A brief summary.
Design patterns are described in the piece as “reusable templates that empower developers to address recurring challenges in software design.” Type: Medium. It informs the reader that a design pattern is not complete code, but rather a plan or idea that can be used in various situations. It uses Christopher Alexander’s ideas to show how patterns came to be and sees the famous book by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (1994) as a turning point. Medium Later, the piece divides patterns into three common groups: creational (how objects are made), structural (how objects and classes are put together), and behavioral (how objects talk to each other). Medium+1 Instance Singleton (ensures one instance), Factory Method (abstract object creation), Observer (object communication), and other examples are given. Patterns have perks like better code reuse, maintainability, communication among developers (shared vocabulary), and the ability to be extended. Medium. It also doesn’t sugarcoat criticism, pointing out that patterns should only be used carefully so they aren’t over-engineered or used in the wrong way. Medium. 

Personal reflection.
I learned more from reading the piece that design patterns are not just academic artifacts, but very useful tools for building and architecting software. I now understand that as I work on projects (for school, fun, or future work), I can look for problems that keep coming up (like “we keep instantiating similar objects in different ways”, “classes in our system are tightly coupled”, or “object behavior changes depending on state”) and think about using a good pattern instead of coming up with a new solution every time. 

Conclusion
Overall, this article on design patterns provided a strong foundation that I can build upon. It made it clear what design patterns are and why they’re important. It also provided me with a clear structure (creational, structural, and behavioral), and it made me think about how I will utilize patterns in my work as I transition into a more business-focused software professional. I will keep this resource and its tips in mind as I learn more about building, designing, and architecting software.

References: 

It was written by Freeman, E., Sierra, K., and Bates, B. First, look at the design patterns. The O’Reilly Media.

Smith, C. Alexander (1979). What’s Always the Best Way to Build? Oxford College Press.

From the blog Site Title by Roland Nimako and used with permission of the author. All other rights reserved by the author.

UML Sequence Diagrams

In this episode, Ashley Peacock, a staff engineer and architect who is passionate about visualizing software ideas, is interviewed by host Akshay Manchale. They examine the reasons behind the underutilization of diagrams in software engineering, the rise and fall in popularity of modeling tools and notations (such as the traditional Unified Modeling Language, or UML), and, most importantly, the continued significance of sequence diagrams. Sequence diagrams have two primary uses, according to Peacock: (1) depicting user flows through a system (actor → service → backend → database) and (2) illustrating message flows between classes/components in code. He highlights the fundamental function of diagram communication instead of discussing the drawbacks of overly rigorous UML adoption.

The reason I chose this Source

I chose this episode because our course on Software Construction, Design & Architecture emphasizes modeling techniques, and I wanted to learn more about how sequence diagrams are used in modern software engineering practice than just the concepts found in textbooks. Hearing a practitioner discuss diagramming in real-world scenarios felt incredibly relevant to me as someone with a background in finance and statistics who wants to improve my technical design abilities (particularly because modeling can be used in business/technology initiatives). 

Reflections And Actions

It became clear to me again while listening to Peacock that what matters most is how well you communicate, not how well you write. I discovered that sequence diagrams are more than just “another UML artifact.” They connect use-case thought (what the user does) and structural modeling (what the system has). Making a sequence diagram of the steps “User submits order; OrderService validates; InventoryService checks stock; PaymentGateway processes payment; confirmation sent to user” can help everyone (business, product, architecture, and development) understand the flow. At the beginning of my work, I also put too much emphasis on static diagrams like class and ER diagrams and not enough on the temporal aspects of “who calls whom when” and “what’s the sequence.” I learned from the show that sequence diagrams can be used as a contract: you can map out how things work together before you write any code, which helps you avoid misunderstandings.

To improve my future work, I will choose a key scenario (like “customer checkout,” “report generation,” or “billing and collections”) and make a sequence diagram to help me understand it better when I do system analysis for a project, whether I’m a financial or technical analyst or designing a business process. The chat changed how I think about tools. I’m going to start using lightweight diagramming tools (Mermaid, PlantUML, etc.) that let diagrams live with code instead of being buried in PowerPoints. I can see that sequence diagrams aren’t just ideas; they can also be used to communicate design ideas, make sure that architectures are aligned, and keep records.

Citation

I’m Ashley Peacock. (5/31/2023). Ashley Peacock talks about diagramming in software engineering on SE Radio 566. se-radio.net

From the blog Site Title by Roland Nimako and used with permission of the author. All other rights reserved by the author.