Link: https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/

In the blog post “Best practices for REST API design,” the authors go over important guidelines for designing any type of web service through the REST architecture style. They first go over the definition of a REST API, which is an interface that follows stateless communication and cacheability, as well as other constraints. They then show off a set of recommendations for good practices, such as using nouns and not verbs in endpoint paths, accepting and responding with JSON, logically nesting hierarchical resources, handling errors with standard HTTP status codes, and many more. The blog post emphasizes greatly that keeping names consistent and adhering to web standards will ultimately make APIs easier for maintainers and clients, as it will be easier for clients to use and maintainers to support. It would also make it much easier for systems to scale properly.

I selected this blog post because we are currently talking about this topic, and we have a homework assignment going over this topic so I thought it would be helpful to gain a deeper understanding of it. Also, in past courses, such as Unix Systems Programming, we would focus on architecture and backend systems, but I never really gave it a deeper look. This blog post gives very clear guidelines for REST API design, which can be very valuable in my career if I end up working in software or if I have to build or interact with APIs in the future. In the future, I plan on applying these principles if I ultimately have to design or integrate REST services, which could be through setting up a microservice in the cloud or even connecting to one as a consumer. I will definitely look to follow the guidelines listed in the blog post, as I believe that following those will provide a good baseline for my work. These API design patterns can also help me with projects, as I can ensure that my interface layers are clean and intuitive.

Overall, I thought that this blog post was very helpful and informative, as it provided a lot of clarity on the guidelines for REST API design. Their point about using nouns in endpoint paths was a very good point, as it is better for HTTP verbs to be doing the action. While it is a small naming decision, it can end up making a big difference when it comes to readability and maintainability. In the end, this blog post improved my understanding of REST API design practices and showed me that good design isn’t just about the efficiency of the algorithms and resources, but it is also about the service and client experience.

From the blog CS@Worcester – Coding Canvas by Sean Wang and used with permission of the author. All other rights reserved by the author.

I decided to read Pavan Kumar S’s blog, “Refactoring 101: Code Smells – Bloaters.” This post explains a specific code smell called “bloaters,” which starts when parts of your code grow too large and become difficult to maintain. The topic of this blog connects to our course work and topics on design principles, going over code smells and refactoring just like we’ve done in our lectures and homework.

Pavan Kumar describes bloaters as a sign that a program has become overcomplicated and cluttered. He picks out examples such as long methods, large classes, and long parameter lists. Each of these examples show a situation where code tries to handle too many responsibilities at once, causing poor readability and maintainability. Kumar suggests several refactoring techniques to combat these problems, including Extract Method, Extract Class, and Introduce Parameter Object. These techniques can be used to simplify your code by breaking large structures into smaller, specialized units. The blog explains that the goal of refactoring is not to change the external behavior or output of the program but to improve its internal structure so that it remains easier to understand, test, and extend in the future.

This blog appealed to me because it provides a clear explanation of a problem I often run into in my own programming projects. When writing assignments or personal code, I tend to write long methods that handle multiple tasks without modularity or specialized methods in mind. I’m aware of this bad habit because I mostly do it as I usually work with smaller projects that don’t require too much. Although it works initially, the code quickly becomes messy and difficult to modify or expand. Reading this blog was helpful for me since I recognized I recognized my bad habit when writing code.

What stood out most to me was how important refactoring can be in design principles. This was showcased in the duck homework where we have to refactor bad code. This only reinforced the idea and helped me better digest that concept of refactoring. A bloated method or class commonly goes against these ideas by combining too many responsibilities in one place. If you refactor and divide functionality into smaller pieces, each part of the code is more manageable and much cleaner. This short concept reinforced the idea that refactoring is not simply about cleaning up code, it’s good design habit.

From this reading, I picked up on the idea that refactoring does not have to be a massive rewrite or a stressful task. Small improvements like breaking large classes into manageable ones can prevent the slow build up that often happens in growing projects. Hopefully, I can incorporate regularly reviewing my code for signs of bloat and make refactoring part of my skillset.

https://medium.com/testvagrant/refactoring-101-code-smells-bloaters-f80984859340

From the blog CS@Worcester – Coding with Tai by Tai Nguyen and used with permission of the author. All other rights reserved by the author.

My understanding of Scrum is that it isn’t just a process or checklist; it’s a lightweight framework for solving complex problems through collaboration, transparency, and continuous improvement. The Scrum Guide defines Scrum as: “a lightweight framework that helps people, teams, and organizations generate value through adaptive solutions for complex problems.” The framework is based on … Read more

From the blog CS@Worcester – BforBuild by Johnson K and used with permission of the author. All other rights reserved by the author.

When I first started learning about REST APIs, I thought it was just about how apps talk to each other over the internet. But after reading the REST API Tutorial, I realized that REST is much more than just sending HTTP requests. It’s an entire way of thinking about how systems communicate efficiently and reliably. … Read more

From the blog CS@Worcester – BforBuild by Johnson K and used with permission of the author. All other rights reserved by the author.

The blog post I decided to talk about is on “Design Smells” in software development. I chose this topic because we’ve touched on it in class during assignments where we matched the correct design smell to its definition. It’s an important concept to understand since we’ll be working with API designs and need to know how to avoid these issues. In the post written by Keith Casey, he compares design smells to your car sounding weird or your “Spidey Senses” going off, subtle signs that something is off with your code or design. He focuses on four main design smells: Inconsistent naming, CRUD-only APIs, Customer-specific features, and Per-resource versioning.

He gives a realistic example of inconsistent naming with variables like interest_rate, intRate, and iRate. It might seem like a small problem, but those tiny differences can cause major confusion (Opacity). While it may look like just a style issue, it often shows that team members have different understandings of the same concept. I’ve seen this happen in class, where one student uses userName and another uses username. It makes the code harder to read and maintain. In the future, I think it’s important for teams or individuals to agree on consistent variable names early, so the code stays clean and easy to follow.

The next design smell discussed is “CRUD over HTTP”. I wasn’t too familiar with this one, so it was interesting to read about. This happens when an API just wraps a database without adding any real logic (Needless Complexity), which the author calls a “glorified database.” Using methods like GET, POST, PUT, and DELETE might seem correct, but if your API only moves data around, it’s not doing much. A good API should validate input, include logic, and make the system useful beyond basic storage. We’ve talked about these HTTP methods in class, learning how each one interacts with data, so this gave me new ideas. Before, I only thought about what each method did; now I’ll think more about what the API is modeling and how it supports the system’s purpose.

For the last two design smells, customer-specific functionality and per-resource versioning, both show how small design changes can turn into big headaches. Customer specific functionality happens when a team adds a feature to please one customer. It sounds harmless, but every tweak adds complexity, more testing, and a higher chance for things to break. The author makes a good point to inspect each request carefully and compare it with the API’s design. The last design smell gives each resource its own version number. It may sound flexible, but it quickly becomes messy and confusing for users. These two examples show that good design means knowing when to say no and keeping things simple within the API.

Overall, this blog post helped me understand how small details can affect the bigger picture in software design. “Design smells” can be avoided with a little attention and ensuring not adding things than can be needlessly complex.

Source: https://caseysoftware.com/blog/api-design-smells

From the blog CS@Worcester – Mike's Byte-sized by mclark141cbd9e67b5 and used with permission of the author. All other rights reserved by the author.