Modern web applications are built on top of REST APIs, which provide the essential connection between the client and the server. This week, I discovered a blog called “Best Practices for REST API Design” by John Au-Yeung and Ryan Donovan which outlines important techniques for developing secure, performant, and user-friendly APIs. Because JSON is widely accepted and lightweight, it promotes its use as the standard data format. While HTTP methods like GET, POST, PUT, and DELETE determine the action, logical endpoint architectures that rely on nouns rather than verbs are crucial for clarity. Although it improves readability, resources should be kept simple to prevent complexity.

The blog discusses how to handle problems politely by giving easily comprehensible error messages to facilitate debugging and employing relevant HTTP status codes (e.g., 400 for Bad Request, 404 for Not Found). It also highlights the need of using query parameters for pagination, sorting, and filtering when handling big datasets. For protecting APIs, security measures including role-based access control, SSL/TLS encryption, and the least privilege principle are essential. Although caching is emphasized as a way to improve performance, developers should make sure it doesn’t produce stale data. Lastly, it is advised to version APIs, frequently using prefixes like /v1/, in order to guarantee backward compatibility and permit incremental enhancements.

Since we’ve been learning about REST API design in class, I chose to read a blog about it in order to gain a deeper understanding of best practices. In addition to explaining each essential aspect of REST API design, such as JSON usage, appropriate endpoint naming, error handling, security, caching, and versioning, I selected this blog because it also provides code blocks as examples, which helped readers understand and visualize the concepts more clearly.

What caught my attention the most was the part about using logical nesting for endpoints. It described how APIs are made easier to use and comprehend by grouping relevant endpoints. It also made the point that endpoints shouldn’t replicate the database’s structure. This increases the security of the API by shielding private data from attackers. I became more aware of how endpoint design may affect security and usability after reading this. This demonstrated the significance of properly planning endpoint architectures.

This article impacted my perspective on API design by emphasizing the necessity of striking a balance between usability and simplicity. I want to use these ideas in future projects by making solid security procedures, efficient error handling, and well-defined endpoint structures top priority. By using the strategies covered in this blog, I intend to create APIs that are effective and simple for developers to use, guaranteeing that they can be maintained and offer a satisfying user experience throughout time.

From the blog CS@Worcester – Live Laugh Code by Shamarah Ramirez and used with permission of the author. All other rights reserved by the author.

Similar to SOLID, GRASP is an acronym for a set of design principles used in object-oriented programming to clearly define responsibilities within a software system. GRASP stands for General Responsibility Assignment Software Patterns, and focuses on 9 different patterns or principles. A blog on kamilgrzybek.com called “Grasp – General Responsibility Assignment Software Patterns Explained” does a really good job at explaining all nine of the different patterns, as well as gives helpful examples of each. According to the article, “GRASP is a set of exactly 9 General Responsibility Assignment Software Patterns. As I wrote above assignment of object responsibilities is one of the key skill of OOD. Every programmer and designer should be familiar with these patterns and what is more important – know how to apply them in every day work (by the way – the same assumptions should apply to SOLID principles.” This quote shows that the GRASP principles are just as important to know as the SOLID principles. I think that everyone should learn the GRASP principles alongside the SOLID principles, and I plan on trying to use them in the future.

The nine principles consist of the following:

Controller
Creator
High Cohesion
Indirection
Information Expert
Low Coupling
Polymorphism
Protected Variations
Pure Fabrication

Controller tends to represent the device that the software is running within, such as the overall system. It also represents a use case scenario within the system operation occurs. Controller depends on high level design of the system being used, but generally we need to define the object which orchestrates the business transaction before it is processed.

Creator is a hard principle to explain. I think the example that the article gave is helpful. “Problem: Who creates object A? Solution: Assign class B the responsibility to create object A if one of these is true (more is better): B contains or compositely aggregates A, B records A, B closely uses A, B has the initializing data for A.”

High cohesion is how well the elements in a class work together. If a class has low cohesion, then it has a lot of unrelated data or behaviors inside of it. Classes with high cohesion, meaning it has data and behaviors that are all related to each other, are a lot more efficient.

Indirection avoids direct coupling between two or more things and allows an intermediate object to mediate other components.

Information expert assigns a class the responsibility of holding all of the information needed to fulfill the object and its needs.

Low coupling is when objects are more independent and isolated, rather than being completely dependent on other parts of the system. This helps reduce the risk of breaking the system.

Polymorphism is an essential principle of OOD. It allows different types of objects to be treated as a single type.

Protected variations identify points of predicted instability and assign responsibilities in order to create a stable interface around them.

Pure fabrication assigns a highly cohesive set of responsibilities to an artificial class that doesn’t represent a problem domain concept when you don’t want to violate high cohesion and low coupling.

Link: https://www.kamilgrzybek.com/blog/posts/grasp-explained

From the blog CS@Worcester – One pixel at a time by gizmo10203 and used with permission of the author. All other rights reserved by the author.

Throughout the year we have used REST API in class more and more. Through the microservices kit activities I found more interest in the use of REST API. I sought out more information on them to expand my knowledge through an article on REST APIs. The article I found is REST APIs: How They Work and What You Need to Know by Jamie Juviler

The article begins by explaining the importance of REST APIs. They are a widely used framework that allows applications to communicate over the web by following a set of design principles. The article explains it is used to enable data sharing and integrations between systems, allowing software to interact with external services, improving functionality and user experience. The article continues by explaining how they work. By allowing clients to make requests to a server for resources, the server then responds with the current state of the requested resource, usually in a standard format like JSON. The API can also allow clients to modify or add resources on the server. The article explains there are six key principles to know:

1. Client-Server Separation: REST APIs separate the client and server, meaning that the client can interact with the server without needing to know how the server works internally.
2. Uniform Interface: RESTful APIs require a standardized way of interacting, usually through these HTTP methods: GET: Retrieve data. POST: Create new data. DELETE: Delete data. PUT: Update existing data.
3. Stateless: Each request to the server is independent and must contain all the information necessary for the server to fulfill the request.
4. Layered System: In a REST API, there can be intermediary layers (e.g., security layers, load balancers, or caching layers) between the client and the server. These layers should not impact the client-server communication and should be transparent to the client.
5. Cacheable: Responses from the server may be cacheable, meaning that the client can store the data locally and avoid repeated requests for the same resource.
6. Code on Demand (Optional): This optional feature allows servers to send executable code (like JavaScript) to the client, enabling the client to execute this code locally.

The article then explains the benefits of REST APIs, which include flexibility, scalability, interoperability, simplicity, and cost-effectiveness. Juviler then explains how to set up REST APIs with an admin and the article concludes with some examples of the use of REST APIs. 

Rest API has become something very important in class and because of recent assignments I wanted to learn more. Through this blog I understand REST more thoroughly, and the reasons for using it. I understand its feasibility and use for microservices back-end architecture as seen in Thea’s Pantry.

Source:

https://blog.hubspot.com/website/what-is-rest-api

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.

This week I wanted to blog about Rest API. The repository that we have been working on in class has a decently large backend that uses a wide variety of methods to act as a good example and introduction of Rest API. I wanted to look into it and try to find more examples to look at and get a better understanding by looking at implementations that either had a different format or was used for different purposes. While looking I found a blog that detailed the documentation that developers have made a standard to put with code that aids in understanding.

The article starts off with some common mistakes that can really decrease the effectiveness of your documentation such as not enough examples, the lack of English explanations, and unmaintained documentation. As aspect that the article touches upon is that the documentation should be written to be understood by entry level developers, which makes sense as your implementation shouldn’t be opaque to the users. The article provides a survey taken by web developers that ranked the most desired features of API documentation, and ranks examples, status, and error messages in the top five. This makes sense as these are some of the things that contribute most to being able to understand already existing code. Spec-driven development is also explained here and talks about using software like Swagger to keep track of and simplify your code to easily understand how the program uses the data. The blog also puts emphasis on the industry standards that should be used, and it goes a long way to help users get a grasp of new code when they start to look at new projects.

This post was helpful in understanding how to read other repositories of API, especially as it was written in the form of the writer’s or maintainer’s point of view. Although I have not yet and don’t plan to yet, write and document an API designed by myself, this write-up was equally descriptive for explaining how to read the documentation. I think that this is an extremely useful skill to have because, like in our class assignments, we won’t always be designing something from the ground up and so we need to understand what is already there. The web page had lots of pictures to illustrate the point they were making and to provide examples. It always helps to learn more of these industry standards to be better prepared for real world or out of classroom applications and strengthen your skills as a programmer.

Original Blog Post – How to Write API Documentation

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

This week I found a great blog titled, “Mastering Design Patterns in Java”, that delves deep into design patterns specifically in Java. This piece of work aligns with our course topics and focuses on a programming language that many of us are most comfortable with. The writer, Dharshi Balasubramaniyam, discusses six notable design patterns in software engineering: 

1. Singleton 

2. Factory 

3. Builder 

4. Adaptor 

5. Decorator 

6. Observer 

The focus of the discussion is how to implement these patterns using detailed examples and how they can be used to deal with common coding scenarios like creating objects, managing inter-class relationships, and optimizing object behavior. 

Our work in our course has focused on some of the design patterns that are discussed in this blog, but the rich examples provided here are incredibly valuable when trying to gain a complete understanding of the patterns and learning when to use them. A great example of this is the mention of the Singleton pattern – I am already familiar with this one, but the example being used made the concept easy to remember and understand. The example references the simple idea of the clipboard. If we had more than one instance of the clipboard being accessed by the user of a device, it would be very likely to have conflicting data saved – to avoid this issue we can apply the Singleton pattern to ensure that there is only ever going to be one clipboard instance at any given time. The writer provides the code which enables this example and shows the value of using this design pattern. 

One new pattern I learned about was the Builder pattern which focuses on simplifying object construction with required and optional properties. The pattern works to manage the parameters by using a constructor with the required properties and different setter methods with optional properties by using an object class and an objectBuilder class. This pattern provides flexibility for the object being created – the given example creates a user with required properties of name and email and optional properties of phone and city. In the case of the example, we can note that the properties will have their own functions for setter methods which return an objectBuilder object – if the function does not get called to set a new value all optional parameters will contain the string “unknown”. This technique makes the code easy to understand and ensures we are not getting errors due to missing parameters as they will always contain some string.  

Using this blog to practice and learn from new examples is extremely helpful and will contribute to the enhancement of my skills as I continue to learn and get more comfortable with writing good, clean code the first time. By implementing the examples shown in the article, I can start noticing opportunities to apply these design patterns in my own work avoiding hours of refactoring code later.  

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

Anti-patterns are best described as behaviors or approaches to problems that conceptually may help solve the problem, but in practice are a detriment to the process of doing so. In software development, this can come in many forms, whether ‘cutting corners’ by reusing old code or trying to condense behaviors into one class/object. Ultimately these decisions we make as developers come from a place of genuine concern. When these design patterns remain unchecked, they begin to rot in our code and cause many problems, some of which are contradictory to the intention of originally incorporating them.

In the article Anti patterns in software development, the author Christoph Nißle describes several anti-patterns that occur in software development and the consequences of each. Three anti-patterns resonated most with me, as I could see how someone could accidentally implement one of them. The first of which is what Nißle calls Boat Anchor. It represents code that *could* be used eventually, but for the time being, has no relevance to the current program. By keeping this code, the developer is contributing to visual bloat. Not only does this make finding specific lines harder, but once other developers are included on the project they may have questions about how this code will be implemented. To counter this anti-pattern it’s good practice to only keep code that is prevalent to the program’s functionality AND is currently being used by the program. The second anti-pattern I found interesting was Cut-and-Paste Programming. As the title suggests, it occurs when programmers reuse code from external sources without properly adapting it to their current project. This code can also come from the same program. Under both circumstances this code will cause errors, as it’s not a ‘one size fits all solution’, furthermore the code being pasted could have errors. These can be remedied by “creating multiple unique fixes for the same problem in multiple places”(Nißle), but each unique fix requires time and this time could have been spent creating code for the specific problem rather than reusing code. Lastly, the Blob pattern is one that I have personally fallen victim to several times. This pattern has the developer trying to make objects/classes as dense with functionality as possible, but this complexity acts against the single responsibility principle. Classes (and objects) should be solely responsible for one behavior if we include too many then the function of that specific class becomes unclear. The Blob pattern can easily be fixed by dissolving the blob class into several single-responsibility classes. It’s best to catch poor practices such as the Blob early in development to minimize the amount of refactoring that’s needed to fix the code.

As mentioned before, I’ve fallen victim to these anti-patterns as conceptually they save time in the development process. However, the time often saved is eclipsed by the time required to fix errors later in development. Properly following design principles will cause development to require more time, but it should reduce the number of errors that would appear if anti-patterns were used in their place.

Link to Article:

https://medium.com/@christophnissle/anti-patterns-in-software-development-c51957867f27

-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.

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.