In our work with REST APIs, namely through the HFOSS project Thea’s Pantry, we have implemented new functionality to the database by updating the HTML specifications and creating new endpoints. During this whole process I did not have a concrete idea of what an API was, nor did I understand what made REST APIs any different from their alternatives. 

In the article What is a RESTful API the authors Stephen Bigelow & Alexander Gillis define what an API is, and what components make an API RESTful, in addition to how they can be used. APIs are defined as “code that lets two software programs communicate with one another” (Bigelow & Gillis). This can be seen through our work in Thea’s Pantry as the specification.yaml file provides instructions for the commands which communicate between the backend and database. In a general flow of control the user interacts with software, this piece of software interacts with the API which then shifts control to the external software. From this point the user can directly interact with the external piece of software (in the cases of methods such as delete and put), or the user can fetch information from it which can be returned to their client-side software. REST stands for representational state transfer, this is a type of software architecture that makes communication between two programs more accessible and easy to implement (Bigelow & Gillis). Users can interact with resources from another program using HTTP requests composed of a method, endpoint, header, and sometimes will require a body. RESTful commands, similar to those of databases (get, update, delete.. etc), can be specified by the developers of the API to have unique functionality. This modularity of command functions is one of the benefits of using RESTful APIs. An alternative to RESTful APIs is SOAP. These both achieve similar functionality, but the methods of doing so are different. For example, SOAP is a communication protocol compared to REST which is an architecture style. SOAP is only compatible with .xml files, meanwhile REST can be used with .xml in addition to other file types. It is worth noting that REST and SOAP are not one-to-one alternatives and can be used together. 

APIs allow developers to extend the functionality of their programs by communicating with other programs. This can be achieved through HTML requests (in the case of RESTful APIs) and nodes (in the case of SOAP APIs). REST APIs favor flexibility and modularity, on the other hand, SOAP APIs are more rigid and require concise specifications. Due to its accessibility, RESTful APIs are more favorable in projects such as Thea’s Pantry. I cannot see SOAP being implemented in Thea’s Panty due to its rigidity as seen through the types of files it uses. REST is much preferred here as we can use javascript files to define the HTML requests that the API will use.

Link to Article:

https://www.techtarget.com/searchapparchitecture/definition/RESTful-API

-AG

From the blog CS@Worcester – Computer Science Progression by ageorge4756 and used with permission of the author. All other rights reserved by the author.

URLs:
Article on SOLID: https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/
Video mentioned: https://www.youtube.com/watch?v=j-6N3bLgYyQ

One video has always caught my attention because it clearly illustrates why SOLID principles are so important. I will reference two sources in this post for better understanding, in case you want to explore the topic further. However, I kindly ask you to watch the video linked at the beginning for my comments to make sense.

I chose an article to complement the video because it offers a more approachable explanation of SOLID principles and, as stated, explains them in plain English. The video features a dad following instructions from his kids to make a peanut butter and jelly sandwich. The issue here is that such a task may have become so automatic for us that we no longer think about every single detail involved.

How is that related to programming and SOLID principles? Well, it’s quite similar. At its core, code consists of lines and lines of instructions written for a machine to execute. To achieve the intended goal, these instructions must be precise and correct; otherwise, we can encounter numerous issues. As the video demonstrates, the lack of precision in the kids’ instructions led to some funny outcomes: first, the dad stacked two slices of bread on top of each other without doing anything else. In another instance, he ended up with a piece of bread with a “bit” of peanut butter on it, a whole bottle of jelly, and another slice of bread on top.

Did I just make a typo by saying a bottle of jelly was between two slices of bread? No, that did happen. This highlights what occurs when you assign certain instructions—or, in programming, functions (Single Responsibility Principle)—more than one purpose or intent. While a peanut butter and jelly sandwich recipe might not fully embody all five SOLID principles, the Single Responsibility Principle (S in SOLID) alone is enough to demonstrate the importance of clear and focused design in coding.

The lack of clarity and precision in the sandwich instructions led to various unwanted results. Although the instructions made sense to the kids, they didn’t work well for anyone else. Similarly, when writing code—whether for homework, work, or even personal projects—these principles should never be overlooked. I believe following such practices is part of a developer’s ethical responsibility.

At the end of the day, even if I’m the one reviewing my code a year later, I might struggle to understand it without proper adherence to these principles. You might wonder, “How is it possible not to understand what you wrote yourself?” Well, that’s exactly what happened to me yesterday while refactoring some old code. I encountered several parts that I couldn’t make sense of, so I had to revise and apply these principles to make them comprehensible.

From the blog CS@Worcester – CS Today by Guilherme Salazar Almeida Nazareth and used with permission of the author. All other rights reserved by the author.

This week, I decided to find another Reddit post as the last Reddit post I covered I felt had a lot to take from it as it was a community of people giving their real thoughts and feelings on a certain aspect of Comp Sci. Today, I found a post on the importance of object-oriented design, and people discussing the different values it holds.

One of the top comments on the post is about how understanding object-oriented design is a great foundation for writing clean code, which is something we discuss in CS-348. It isn’t necessarily something you can just learn on the go while working, and, rather something you should try to learn about as much as you can while in school to then apply in the workplace. I’m very appreciative of reading this actually as I typically like to think most stuff gets easier to apply/learn as you’re working, but if a lot of people agree that you should understand as much as you can about object-oriented design BEFORE actually starting a job, then it’s certainly something I’m going to want to have down. The general consensus wasn’t that you won’t get better at applying these principles as you progress in your career but that you should have a strong foundation of knowledge on these principles going into your career as it is crucial to know certain aspects of it, like when one object ends and another begins or how to model object relations.

OOP is so important, many of the Redditors on this post also seem to agree that you’ll find it very hard to even get a job if you don’t at least have a base understanding of the concepts. It isn’t necessarily hard to understand a lot of these concepts as they’re pretty fundamental, but you should be able to answer questions either directly related, or somewhat related to OOP in job interviews as if the interviewer begins to think you may not know what you’re talking about, you may quickly lose your opportunity at that job. Some people did make comments explaining how it does depend on the concept of the job too such as the primary language you’ll be programming in or even the exact role of your job, but the general consensus still seems to be that you want to have at least a strong fundamental understanding of object-oriented design and the ability to apply it’s principles in your coding.

There are over 100 comments on this post that all make great points on why understanding these principles are very beneficial to you, even just a fundamental understanding of them can help you go a long way. It seemed to me that people had varying levels on how important overall understanding all of these principles are, but they all seemed to agree that knowing the basics of them and being able to apply them all to some degree in your coding, as well as being able to understand and talk about them (in interviews especially), is certainly the most important/beneficial thing you could do.

Source: https://www.reddit.com/r/learnprogramming/comments/z2fcyb/how_important_is_object_oriented_design/

From the blog CS@Worcester – RBradleyBlog by Ryan Bradley and used with permission of the author. All other rights reserved by the author.

Back again with another design pattern, and this time with one I have absolutely no idea about. I chose this particular video because I like this guy’s videos and I think he does an excellent job with explaining things in a way I can understand and I wanted to know some more design patterns. From another video by Christopher Okhravi I am learning about the Observer Pattern. Mr.Okhravi goes over this pattern with a lot of visuals which I very much appreciate and also goes into great depth with this pattern, but what does this pattern do? This pattern which involves utilizing one object that acts as the “Observable” and then this Observable object has a relationship with many “Observer” objects where if there is a change inside the Observable the Observable pushes out a change to all the Observer objects it’s connected to.

Looking at this pattern it’s kind of hard for me to wrap my head around an example of what it could be used for, but I did understand how the system itself would work, it just feels somewhat more complicated than I can really handle at this moment. Otherwise, though I did feel like I learned quite a bit about this pattern like how different languages have different variations and limits on what an observer pattern can do. Though the somewhat odd nature of the pattern does confuse me, even though it looks so simple. Like how it’s kind of cyclical where we are passing observer objects to the observable and then back again. This just really confused me but I think I’ll need to watch the video again to really grasp it fully. The example Okhravi uses of a “weather station” helped to really elucidate what I was confused about, where we have the physical components displaying the data and then the actual data that is being monitored by the weather station and watched by those observer components.

I think for the future I’m not really sure how often I’ll be using this pattern but I can foresee some use cases for it as it might be very useful when I need constant monitoring of something. But I think evidently even if I can’t come up with any ideas now I definitely think in the future I’ll be making use of this pattern and that I need to learn about even more patterns so that I can apply them where I need them, and to maybe go back and relearn those initial patterns I learned about.

Here’s the video:

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

Growing up, sometimes when I would Google search things, the page would not load and instead, it would give me a code, typically a 404. I never understood what it was or what it meant until recently. The 404 is a REST API response code, a code that the server returns when a web page or URL requests something. There are a bunch of codes, ranging from successful requests to malformed URLs to unstable connections to the servers. But there is more to them than just response codes.

In this blog post, the Postman Team talks about everything REST API related, including their history, how they work, their benefits, some challenges, and go over some examples. REST API uses resources, which can be a number of things, such as a document, an image, or multiples of them. REST is able to use an identifier to determine the type of resource being used in interactions. REST API uses methods, which is the type of request that is being sent to the server. These methods are GET, PUT, POST, DELETE, and PATCH. Each does something different from each other, allowing the user and the server to do a multitude of actions. GET does what the name suggests, it asks the server to find the data you asked for, and then it sends it back to you. DELETE deletes the specified data entry. PUT updates the specified entry, PATCH will do a similar thing. POST will add a new entry. With these methods, they return codes, describing what happened with the request. 200 is a successful response, 201 is a successful creation, etc. There are a number of codes, going from 100 to 599, each with a different response. REST API is flexible, allowing you to do more with them. REST API is used mainly for web use, but can also be used in cloud services and applications. The benefits of using REST API include scalability, flexibility and portability, independence, and lightweight. The challenges of it though are endpoint consensus, versioning, and authentication. The blog post goes into detail about all this in their post.

I chose this blog post because it did a good job of explaining everything about REST API. It even has a YouTube video listed in the post, which also explains what is in the blog post. APIs are used everywhere, so it is interesting to learn about something that is essentially a part of all computer related things. Although this is REST API related, there are a number of APIs, each with something different that they offer.

From the blog CS@Worcester – Cao's Thoughts by antcao and used with permission of the author. All other rights reserved by the author.

As my year progressed I wanted to better understand the basic principles of software design and sought out the SOLID principles after hearing about them throughout college. I had not yet put the time into properly learning and practicing them and came across a blog putting the principles into text simply and with excellent examples. The article’s title is The SOLID Principles of Object-Oriented Programming Explained in Plain English By Yiğit Kemal Erinç

The article begins by identifying what the SOLID principles are and their importance. These principles are five key guidelines for object-oriented design that help developers create maintainable, flexible, and understandable code. These principles are provided in great detail, with several coding examples and potential drawbacks or dangerous pitfalls. They are the:

1. Single Responsibility Principle (SRP): A class should have one responsibility and one reason to change. By adhering to the SRP, you minimize complexity, avoid conflicting changes, and simplify version control and collaboration.
2. Open-Closed Principle (OCP): Classes should be open for extension but closed for modification. This means new functionality can be added without altering existing code. This is often done by using interfaces or abstract classes. 
3. Liskov Substitution Principle (LSP): Subtypes must be substitutable for their base types without altering the correctness of the program. 
4. Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they don’t use. This principle advocates for creating small, specific interfaces rather than large, general-purpose ones. It ensures that classes only implement methods relevant to their functionality, and there is less bloat and redundancy in the code.
5. Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules, but both should depend on abstractions. This means This promotes flexibility and low coupling, making systems easier to extend and modify.

The key takeaway presented in the conclusion is that by following SOLID principles, developers can write cleaner, more testable, and scalable code.

The SOLID principles are essential and key learning blocks for building efficient code. This is a topic that has been addressed in class as design smells and patterns. By learning this through the lens of SOLID I was able to reconcile the importance of that topic in building good code. Through the CS-343 course, I was looking to understand those design patterns better, and by understanding them as SOLID principles I am able to better grasp them. I will be prepared to answer questions regarding SOLID principles in context thanks to this article in combination with the class material.

Source:https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/

From the blog CS@Worcester – WSU CS Blog: Ben Gelineau by Ben Gelineau and used with permission of the author. All other rights reserved by the author.

Intro

In software development, documentation often takes a backseat to coding, testing, and deploying. However, software documentation is the backbone of more easily maintainable, scalable, and collaborative projects. This blog post by David Oragui gives useful information on why documentation is essential and how it supports both developers and end-users throughout the software lifecycle.

Summary of Source

The blog post explores the role of software documentation and offers practical advice on creating and maintaining it effectively. The main sections are:

1. What is Software Documentation?: A definition and explanation of how it serves as a guide for developers, users, and stakeholders, providing clarity on a system’s functionality and usage.
2. Types of Documentation: A breakdown of key categories, including user documentation, developer guides, technical documentation, and process documentation.
3. Best Practices for Writing Documentation: Practical tips, such as structuring content logically, using plain language, and keeping documentation up-to-date.
4. Using Software Documentation Tools: The different type of documentation tools and the reasons to consider them including automation, collaboration, and accessibility

Why I Chose This Blog

I selected this blog because it is a concise resource that explores all there is to know about documentation, making it a great guide to refer back to when needed. In my coursework, the focus has largely been on coding, but I’ve noticed that a lack of proper documentation can make even the best-written software hard to use and maintain. This blog stood out for its clear and actionable advice, which is especially valuable as I create projects and prepare for internships.

Reflection

The blog’s structured approach to explaining software documentation makes it great as an introductory resource. One section that particularly stood out was the breakdown of the different documentation types. It clarified the different audiences for documentation end-users, developers, and stakeholders, and how each requires tailored content. For example, user documentation should be simple and accessible, while developer guides need to be more technical and detail-oriented.

This difference in target audiences was an eye-opener, even though it does seem obvious when it’s said. There’s no reason to have documentation about technical details that an end-user will see because they won’t understand it or even need to. Whenever I thought about software documentation before, it was just a one size fits all document that explained the technical details of the software.

Another valuable takeaway was the emphasis on keeping documentation up to date. It made me consider the consequences of never updating documentation and having incorrect information that could end up causing a lot of trouble. When the point of documentation is to make it easier for all parties to understand a project, outdated docs would contribute to the very problem it’s trying to solve.

Future Application

Moving forward, I plan to apply these best practices to my projects. I will make sure to make different documentation resources for different target audiences, also making sure to update the docs every time a change is made to make sure there is no confusion with outdated information. Software Documentation simply makes the whole process of understanding and maintaining code a lot easier so there is really no downside to adding quality documentation to a project.

Citation

Software Documentation Best Practices [With Examples] by David Oragui

https://helpjuice.com/blog/software-documentation

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.