REST API Designs

Week-15: 12/20/2024

This blog post really helped me understand how important design patterns are for making REST APIs that are easy to use and can handle a lot of traffic. The post talked about things like naming resources consistently, breaking up big chunks of data into smaller pieces, and making sure that updates don’t break older versions of the API.

One thing that really stuck with me was how important it is to name your resources consistently. The post emphasized that using standard and intuitive naming conventions makes APIs predictable for other developers. It’s like having a well-organized filing system—if everyone knows where things are supposed to go, it’s much easier to find what you need.

The post also talked about things like versioning and error handling, which are super important for making sure that your API can evolve over time without breaking things for people who are already using it. Versioning ensures backward compatibility as APIs evolve, which means that even if you make changes to your API, older applications that use it will still continue to work. Error handling is all about giving developers useful information when something goes wrong. The post mentioned that providing informative error responses can help guide developers who are using your API. I’m definitely going to be focusing more on these aspects in my future projects.

The reason that I chose this blog post was because it aligns closely with what I learned in the class. Our class discussions often emphasized the best practices for creating maintainable, user-friendly APIs, and this post serves as a practical extension of those theoretical concepts. I wish I had read this article before some of my homework assignments; it would have made it easier for me to understand the assignments. Additionally, its concise, actionable guidance provides a clear framework for applying these principles in real-world scenarios.

Overall, this blog post was a great way to connect the theoretical stuff we’ve been learning in class with how things actually work in the real world. It’s one thing to understand these concepts in theory, but it’s another thing to see how they’re applied in practice. This blog post provides practical insights into designing APIs that are easy to use and can be scaled up as needed. It’s given me a much better understanding of how to create APIs that are not just functional but also developer-friendly and built to last.

Blog link: https://blog.stoplight.io/api-design-patterns-for-rest-web-services

From the blog CS@Worcester – computingDiaries by hndaie and used with permission of the author. All other rights reserved by the author.

Open source planning how it can be leveraged

The planning process is an open source project is often created and monitored by the maintainers. This blog intends to go over the commonalities found by Safia Abdalla in open source planning mentioned in her article “Open source excursion: The poetry of planning”. I chose this topic because it relates to both the section in class where we went over licensing, which included open source licenses, and the section where we over different planning philosophies like scrum.

The first shared tendency between open source maintainers Abdalla lists planning with the intent to build excitement in the community that might hold many of your future contributors. Maximizing the outreach your plan gets among possible contributors and consistently providing updates when changes are made attracts attention towards your project, increases your chances of acquiring new contributors, and encourages existing contributors. Another common planning practice Abdalla lists is planning to prioritize. This planning method aims to optimize the process by which user requests and pull requests are fulfilled by distributing the responsibility among a chosen team. This allows for the efficient processing of requests, as well as allows many members of the team to get well acquainted with the user community and their hopes for the team’s project. The last 2 planning methods listed by Abdalla are planning to communicate and planning incrementally. Planning to communicate is a method of planning that, once a projects priorities and goals are well defined, aims to communicate those goals with the community. This leads to more exposure for the project, and possibly more support and contributions to it as well. Planning incrementally is a planning method where members of a team are mindful of the dynamic nature of the planning process, and communicate to the communities interested in the project the same thing, as to not mislead them.

Overall, these commonalities between open source planning all seem like good habits, and practices that would be useful for me to employ as a future open source project maintainer, and would also be useful as a contributor to open source projects to be aware of these tendencies so I can better align my work to the maintainers’ planning strategies. Planning with the intent to build excitement, along with being an effective planning strategy, sounds like it would also help for beginner developers to build a presence for themselves in the communities that are interested in the project that’s employing it.

https://increment.com/planning/open-source-planning/

Link to source blog:

From the blog CS@Worcester – My first blog by Michael and used with permission of the author. All other rights reserved by the author.

Sequence diagram dissection

Along with class diagrams is the topic of a sequence diagram (mentioned in previous blogs). Sequence diagrams are a good way to understand the flow of a program that helps developers when it comes to creating and testing their products.

This blog will go into detail of how to read a sequence diagram and show why they are important.

To start here is the example given from a class activity and the previous blog:

As an overview this is the sequence diagram for a program that creates a student and a day. Courses and appointments are assigned to a student, working as a mock schedule creator. The student has a name, phone number and an email address. Days are a collection of courses and events. The courses have a start time, end time, course code and room number. The appointments have a start time, end time and description. Displaying the day shows all of the assigned courses and events.

With the overview we can look into how all of that information is extracted using just the sequence diagram. Ideally you would want a class diagram as well in order to write the program initially but the sequence diagram also helps explain the flow and give an idea of what should be tested.

Starting from the top we have a user, that being the driver class that someone is using to run the program. We begin with creating 2 days and two courses. The courses variables are listed above the line leading to the order of their creation. Next a student is created. This student is named sam and the associated variables are listed in a similar manner. An appointment is created in a similar manner as the courses.

All of the created courses and events are then added to the list of events. A new course is created and added to the events. Then comes the “testing” portion. By displaying the days you should get outputs that show all of the events. After removing the created appointment and displaying the day again you should see it has been removed.

All of this shows the actual behavior a program should have. Along with giving samples of inputs that can be used to test that the program is working as intended.

Below is the code written to match the sequence diagram:

As one can most likely see. The code itself follows the diagram almost perfectly. The main differences are just the syntax and the way certain aspects are implemented. It’s important to check over the class diagram and code itself to know how to properly implement the sequence diagram.

The power of a sequence diagram is that it gives a developer a basic example of a program’s expected behaviors. For actual proper testing you would want to implement more things that wont be discussed here. However it is a strong stepping stone leading towards that.

From the blog Mikes CS 343 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

The important of code visibility and how to maintain it

Code visibility or the lack of it can introduce many problems that hinder the development process of a project. Some problems that can stem from poor code visibility include the misunderstanding of the function of the code or large portions of it, not defining possible conflicts well enough to avoid future features including them, and generally consuming an unnecessary amount of time. In Allison Wheeler’s blog, “Maximizing developer productivity with code visibility: A Complete Guide”, Wheeler goes over some other possible complications that could arise from poor code visibility, and presents tools like GitKraken as solutions to those complications. I chose this topic as it relates to the importance of clean code and other coding conventions we covered in class.

Wheeler presents the problems of poor code visibility as 3 main points; Lengthy prep time, Risk of conflicts or redundant code, and slow bottlenecked code reviews. The issue of length prep time arises when the function of the code or portions of it isn’t clearly stated and is left to the developer to figure out via time consuming methods, like trial and error. The issue the risk of conflicts or redundant code is related to the previous issue, where, because of time constraints and poor code visibility, the developer has an incomplete understanding of the code’s function, therefore not seeing how an added feature would be redundant or introduce a conflict. The issue of slow bottlenecked code reviews is also related to the misunderstanding of the code function, as when quality tests are conducted to test a change, a misunderstanding of the function of the unchanged code will result in an inaccurate quality test related to a new change. A solution to these problems is presented by Wheeler in the GitKraken DevEx platform, which is a technology with the aim of making the codebase of a project more accessible and decipherable.

Some of the features that improve code visibility include the creation of workspaces, which forgo the need for newly onboarded developers to access repos through the directory and organize all relevant repos in a single space. This removes possible confusion new hires could have with which repo to commit to. Another feature that improves code visibility is the launchpad feature, which organizes inter-repo requests, like merge, push and pull requests, into one space for the user to view. This feature allows developers to see which issues are being worked on and where the progress of the fixes for these issues are.

I can already tell that this information will be useful to me in my professional career, as many of these features resemble those that were in gitpod as we used it in class. Platforms like these seem very useful for streamlining the development process.

Link to source blog:

Maximizing Developer Productivity with Code Visibility: A Complete Guide

From the blog CS@Worcester – My first blog by Michael and used with permission of the author. All other rights reserved by the author.

GIT(ting) My Friend A Promotion

For teams of developers having a centralized repository for code is essential. Git provides an extremely powerful and relatively user-friendly base for teams to collaborate effectively.

After teaching one of my close friends, involved in a development project at work, the basics of class diagrams. They gave her a more hands-on role with the entire development process. Even though she had never worked with programming before, having someone in a business oriented role who could communicate and check over the team of developers was perfect for them.

That’s when she was selected as the product owner for her company’s new website. In a serendipitous twist they were using git as their repository while I simultaneously was being taught about it in school.

The next step was to teach her a basic overview of how it all looks from a developers perspective.

We started with a picture from my professor.

At first glance, I had completely lost her. After explaining that she wasn’t the maintainer responsible for handling all of this her mind was eased a little. The main ideas were just to understand the flow of how the developers were going to be working. All she had to remember was FCBPP.

This acronym I created for her was simple. They would FORK their own copies. Make CLONES of that. Make a BRANCH where they would do their work. PUSH that work kind of like a save. Then create a PULL request. As a developer it is obviously a lot more nuanced and there are more steps involved. But for someone that isn’t actually doing hands on work that was enough.

After getting the gist of it and before getting further into the details of how it would benefit her to know that stuff. We took a look at the stuff she would really be involved with. The product and sprint backlogs.

In git it is actually fairly easy for someone who doesn’t really understand programming itself to look at, arrange and audit backlog items. It would also allow her to check in regularly to see where the team was when her boss would ask questions.

In the real life case while explaining this part we did use the real github of her company but for the sake of confidentiality it will be a new blank project.

I told her to focus on the issue board under planning. It looked similar to this:

With properly labeled boxes and the lists of items and features the team was working on or planned to work on she felt so much more comfortable asking about things and helping plan everything out. After circling around the topic a few more times we realized just how powerful having a product owner who knows this process could be

We also joked with her boss that with me teaching her these things I should be hired as a consultant (small business unfortunately) with a bonus for my professor.

From the blog Mikes CS 348 by Michael St. Germain and used with permission of the author. All other rights reserved by the author.

The role of individual contributors in the development process

For my first blog I decided to talk about how individual contributors can best fulfill their role in the process of developing a project. This is relevant to the course material because the role of an individual contributor, which is mostly to improve the code and coordinating teams of other ICs, is a similar role the members of a development team would have in sprint.

The position that ICs occupy in most projects is a very impactful and influential position, aside from their ability to directly change the code. Despite their limited access to the management side of most projects, their proximity to the code gives them unique perspectives on the possible directions project could take, and what is and isn’t feasible to implement. In David Noel-Romas’ blog “An ICs guide to roadmap planning”, he introduces the problem of the IC who wishes they had comparable influence to the planning process of the project to their influence on the state of the code. Romas’ suggests several solutions to this problem, including identifying stakeholders and planning around the potential impacts the project will have on them through feedback and other means, making sure the management end of the team is aware of your visions for the project and when would be the most convenient times deliver updates and new features, and rationally bounding the work your team can do in the given amount of time, making an effort budget and working according to it. I think these solutions all take care of the problem of an IC who feels they aren’t offering enough input to the planning process well, and do so in a manner where the team dynamic isn’t compromised.

One of the reasons I think these solutions are effective is because they lend themselves well to the team structure of popular development philosophies. For example, if a development team is using scrum, there are points in the development process where an IC and their team can convene with the rest of the team members, like the sprint review, and offer their opinion on the direction and feasibility of the changes desired by other members of the team. The sprint review also allows the ICs to communicate with shareholders and assess. Since there are multiple sprint reviews per project, this allows many chances for an IC to offer their opinion on the planning process.

I can definitely see where this information will be useful in my professional career, as development philosophies like scrum are commonly used, and the input of an IC in the planning process can be essential to delivering a well made product.

Link to source blog: https://increment.com/planning/individual-contributors-guide-to-roadmap-planning/

From the blog CS@Worcester – My first blog by Michael and used with permission of the author. All other rights reserved by the author.

 coding understandable program

For anyone who codes a  program, it is important to not just have a working program, but to have  a  program  that is   easy to understand, whether you publish your program onto github, or you want to  review  your program after finishing it. Clean code is a term that was first introduced by Robert Cecil Martin, also known as Uncle Bob. He wrote a book that gives best practices and tips for writing understandable and working code. 

When creating formulas for writing code, instead of including numbers in a formula, which could lead to confusion for  a number’s purpose in   a calculation. Creating   a variable that explains it’s purpose in a code makes calculation clear. Comments can explain the meaning of a statement in a  code,  and while comments can  attempt to clear up any confusion for anyone viewing code, it should not be used to explain a obvious statement, but to explain certain actions  in code. For constructing functions, it’s best to have a function perform one action, and if a function is very lengthy, a function should be broken down into multiple functions. 

When writing code with multiple nested if else conditions,  to  make a program easier to understand,  if else conditions should be split  into descriptive functions. As someone who has worked with different programming languages, I would want to use the practices of clean code, to write a working program that I can review and understand if i revisit my work.

What Is Clean Code? A Guide to Principles and Best Practices

From the blog CS@Worcester – jonathan's computer journey by Jonathan Mujjumbi and used with permission of the author. All other rights reserved by the author.

The Modern Standard for Collaboration: Version Control

Introduction

Version control is important for modern software development, enabling teams to collaborate effectively, manage changes, and maintain code quality. The blog post “Version Control Best Practices” by Tobias Günther offers 10 tips on how to use version control systems (VCS) like Git more efficiently.

Summary

The blog outlines essential best practices for working with version control systems, focusing on enhancing productivity and reducing errors. There were ten points but here are the top 5 most important in my opinion:

  1. Use Branches: Branches allow developers to isolate changes, experiment, and test without impacting the main codebase.
  2. Commit Often: Regularly committing small changes ensures incremental progress and simplifies debugging.
  3. Write Good Commit Messages: Clear, detailed commit messages help team members understand the context and purpose of changes.
  4. Go Beyond the Basics: Developers should invest time in learning advanced Git features like interactive rebases and cherry-picking to enhance their workflows.
  5. Don’t Commit Half-Done Work: Each commit should represent a complete, functional unit to maintain repository stability and clarity.

Why I Chose This Blog

I chose this blog because version control is a fundamental skill for software development, yet its nuances are often overlooked in coursework. While I’ve used Git for assignments, I realized that my approach lacked the deeper understanding laid out in this blog.

Reflection

There was a big emphasis on commits, which makes sense as commits are an integral part of version control and most of the tips talked about in the blog are practices that I do regularly, such as writing good commit messages. I don’t think it’s particularly hard to understand these standards for version control, and once you know them it’s just the norm to follow them.

Branching was something that I hadn’t known about prior to learning about it in class, but it makes sense to separate each new feature into its own area to work on instead of putting everything in main. This “tip” is really just a necessary way to stay organized and keep the repository and its pull requests in order.

Going beyond the basic features of git like committing and pushing is also a great tip, because although you could navigate git with only the basics, learning the more advanced features like rebasing can help greatly in certain situation where you’d be happy you know how to do it.

Future Application

There were some takeaways from this blog that I could incorporate into my own workflow. I think that I should commit more often than I do. I tend to forget to commit and only do so when I stop working but by then there could be a few features that are all crammed into one big commit. 

Citation

Version Control Best Practices by Tobias Günther

https://www.git-tower.com/blog/version-control-best-practices/#8-agree-on-a-workflow

From the blog CS@Worcester – The Science of Computation by Adam Jacher and used with permission of the author. All other rights reserved by the author.

An Efficient Way to Work: Software Frameworks

Intro

Frameworks play a pivotal role in streamlining software workflow. The blog post “Top 50+ Software Development Frameworks“ by Trung Tran provides an insightful overview of the purpose, types, and benefits of frameworks, making it an excellent resource for anyone involved in the software development world.

Summary of Source

The blog explains the concept of software development frameworks as pre-built tools and libraries that provide a structure for developing applications. It highlights the following key points:

  1. What is a Software Development Framework: A framework is a pre-designed structure of reusable components and tools that streamlines the software development process.
  2. Advantages of Using a Software Framework: Frameworks enhance efficiency, improve code quality, simplify maintenance, and enable faster development cycles.
  3. Disadvantages of Using a Software Framework: Potential drawbacks include steep learning curves, limited customization, and dependency on the framework’s updates and support.
  4. How to Choose a Suitable Development Framework: Developers should consider project requirements, scalability, compatibility, and their team’s expertise when selecting a framework.
  5. 50+ Popular Software Development Frameworks: The blog lists widely used frameworks like Angular, React, Django, Spring, and Flutter, categorizing them based on application types.

Reason For Choosing This Source

As someone learning to build efficient and maintainable software, understanding frameworks is fundamental. This resource breaks down everything needed to know about frameworks before jumping into using them, even listing the top 50 is really useful to see for any project anyone may do.

Reflection

Prior to this blog I didn’t really have a strong understanding of what a framework for software development was. I had heard of popular ones like ruby on rails or spring for java, but I wasn’t sure what it really meant. Reading through this blog, I now feel I have a solid grasp on what they are, and how to choose one. On the topic of choosing one, there aren’t any that are one size fits all that will always be the perfect one to use, and it more depends on the project being worked on and the team behind it. I know frameworks are popular so I hadn’t considered some the disadvantages listed in the blog like the limited customization, where it might feel like you have less control of what your program does because you’re using this outline and can’t mold it as much as you may want to. A lot of times those disadvantages are overshadowed by the positives which is why they’re so often used.

Future Application

I’ve learned that frameworks are a really powerful tool that save a lot of time and help create efficient work, so I’ll make sure to study which framework is best for me to use in the future when working on projects. This blog post also helped me understand the limitations of them so I also know what to look out for in terms of drawbacks for whichever framework I might use.

Citation

Top 50+ Software Development Frameworks by Trung Tran https://www.orientsoftware.com/blog/software-development-frameworks/

From the blog CS@Worcester – The Science of Computation by Adam Jacher and used with permission of the author. All other rights reserved by the author.

How to review code effectively: A GitHub staff engineer’s philosophy

For my final blog post for the semester, I wanted to pick a topic that was different from project management, since I had already written about that a few times. Since our most recent topic in class revolved around GitHub and git commands, I wanted to explore a blog post that aligned with that topic. I came across a blogpost by GitHub staff engineer Sarah Vessels, from the github.blog page, about code review.

In this article, code reviewer Sarah Vessels discusses some practices to help improve code reviewing and make it more useful and efficient for everyone involved. She advises constantly checking your GitHub notifications inbox, anytime you have a spare moment. She also recommends using GitHub Slack Integration. Certain queries can help filter a slack group for finding outstanding pull requests that need review. We used Discord for our class instead of Slack, but as I understand it, Slack is more common in the professional world. I believe Discord has equivalent queries that can be used, anyway. The next piece of advice she gives is to use reviewer teams to manage notifications. While catch-all code owner teams can be okay as a fallback, it’s better to keep the number of code owner teams your own small, so that anything you get pinged for or anything that shows up in your inbox feels relevant to you, and not just something to ignore.

The next part she discusses, which I feel is the most important advice, revolves around giving good, constructive code review that doesn’t across as lazy. Good code review focuses on specifically saying,” I have a problem with this, maybe you should try xyz instead” instead of saying “I don’t like this” or “This won’t work” and leaving it at that. It’s good to ask questions, because the person who authored a pull request has more context for their changes, and gives them a space to explain and justify their reasonings. Personal preferences are fine, but approval should be about the overall integrity of the code. If the changes won’t break anything or affect production, leave the feedback with a comment but still approve the pull request anyway to keep the process moving. This is something I personally appreciate from the author, because while I don’t mind receiving feedback and improving my part of the process, I hate the feeling of holding back the overall process. This allows opportunities to open discussion without causing a holdup.

She has a few other suggestions in her blogpost, like being gracious and using draft pull requests, but I believe the most important things are her advice about the giving good feedback and managing notifications so you feel compelled to give every notification your full attention. I don’t know how much code I’ll be reviewing in the near future, but if I’m ever in this situation, on either side, this is good advice for me to keep in mind and remember.

Link: https://github.blog/developer-skills/github/how-to-review-code-effectively-a-github-staff-engineers-philosophy/

From the blog CS@Worcester – Justin Lam’s Portfolio by CS@Worcester – Justin Lam’s Portfolio and used with permission of the author. All other rights reserved by the author.