This week, I decided to discuss Application programming interface (API) documentation. API documentation is essential for developers to understand how to use the API, integrate it into their applications, and fix any issues that arise. The article “How to Write API Documentation: Best Practices and Examples” highlights the importance of API documentation and discusses practical insights into creating a better developer experience.

The article starts with an informative video discussing the API economy, what API documentation is, and how to write it. It also shows some examples. The article moves on to the common issues developers have with APIs, like being too long, too much technical jargon, un-updated, or inaccessible without registration. The author discusses several ways to remedy these issues by emphasizing that good API documentation needs to be user-friendly, clearly explained, and given examples with FAQs or tutorials. One of the strategies presented to accomplish this is called spec-driven development(SDD), where you generate the documentation while developing the API. We are also given several tools to help create and maintain API documentation, like Swagger and Postman.

I chose this article because APIs are discussed and used thoroughly in our course. The appropriate next step was understanding how developers make software accessible to users and, in doing so, become more accustomed to APIs.

Reading this article gave me several strategies to think over and included great explanations for why they are used. I was unaware of strategies like SDD and writing for entry-level users, but they made a lot of sense after reading the article. Creating the documentation after developing API can lead to errors and inconsistent documentation, frustrating developers. Having the documentation evolve with the creation of the API makes more sense. The explanation for writing with entry-level users in mind was great, too. You might think that all software developers understand API documentation, but each developer has their own experiences, specialty, and knowledge. Tailoring the documentation to everyone is impossible, so aiming for clarity at the entry-level will make it understandable for most developers. It is one thing to hear how to improve your documentation, but seeing data on the main features developers want and issues they get frustrated with makes me feel like the strategies will have a greater impact on the users.

In future projects, I plan to use spec-driven development to ensure my API documentation grows with my project, allowing developers to follow along without confusion. I will also aim my documentation at entry-level users so the resource is accessible to most developers.

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

One of the earlier topics we went over in this course was Semantic Versioning and how many companies or groups will use it to keep track of their development. Sometimes shortened to “SemVer,” Semantic Versioning describes a versioning structure that will better communicate “implications of new versions, such as breaking changes, new features, or bug fixes” (Victor Pierre). It allows developers to have some comfort in knowing what changes will be made or have been made and whether there is some level of risk in moving to a new version. This risk lies mostly in software that have some sort of dependency, such as libraries or frameworks as updates to those can lead to dependent softwares having to update some part or most of their work, and the software not working otherwise. 

Semantic Versioning employs a three-part version number in the format, MAJOR.MINOR.PATCH, with each part signifying a different impact of the release.

• MAJOR: Incremented when making incompatible changes or introducing breaking API changes.
• MINOR: Incremented when adding new features or functionality in a backward-compatible manner.
• PATCH: Incremented for backward-compatible bug fixes or patches.

This is the basic structure for Semantic Versioning but there are many more rules to follow and other cases that will slightly change how the format will look (Victor Pierre). More details can be found on the official Semantic Versioning site (https://semver.org). 

When this topic was first introduced, I recognized it and was quite excited because it’s something I’ve seen quite often in the games I play or in other things related to games. The very first thing that came to mind was modding, especially in Bethesda Games. The Elder Scrolls Series and the Fallout Series are some of the most modded games ever, one of the reasons for this is the fact that Bethesda, some time after the release of a game, will implement modding support and tools. I connected Semantic Versioning to how Bethesda will rarely release a major update to Skyrim or Fallout 4, two of the most modded games ever despite how old they are now. These rare updates will cause the modding community to blow up as nearly every modder will have to update their mods in order to be compatible with the new version. After 10 or so years of these rare but destructive updates, many modders have simply stopped updating their mods, moving on to better things or just not caring enough to do so. It’s come to the point in which people have come together to make “downgraders” to play on an older version of the game to have access to a wider variety of working mods. 

That was a bit of a long story but overall, I think Semantic Versioning is simple but intriguing and most of all, extremely useful. I look forward to seeing changes, patches, updates for games and other software that I use and having access to an easy-to-follow log of just further cements my liking for Semantic Versioning. I’m not so familiar with other ways to keep track of development but this seems like a staple for developers and companies, and one that won’t be replaced so easily.

https://victorpierre.dev/blog/beginners-guide-semantic-versioning/

From the blog CS@Worcester – Kyler's Blog by kylerlai and used with permission of the author. All other rights reserved by the author.

As I wrap up my last blog for the semester, I find myself still contemplating the career path I’ll take after completing my computer science degree. With so many options available in tech, one question that often occupies my thoughts is whether to pursue a role in DevOps or traditional software engineering.

Both fields are integral to the software development lifecycle, yet they have distinct focuses. Software engineering is primarily about designing, building, and maintaining software systems, while DevOps combines development and operations, emphasizing automation, collaboration, and the seamless delivery of software.

To better understand these roles, I explored the article Developer vs. DevOps engineer similarities and differences from TechTarget. This resource provides a clear breakdown of the responsibilities, skills, and career trajectories associated with both paths.

 Why I Chose This Resource

I selected this article because it connects concepts from CS 343; Software Design Principles . It also highlights the distinct mindsets and tools used in these roles, making it easier to relate the information to my interests and career goals.

What I Learned

1. Core Responsibilities: Software engineers focus on writing, testing, and debugging code, while DevOps engineers prioritize streamlining the software delivery process through automation and operational stability.

2. Skill Overlap: Both roles require proficiency in programming languages and version control systems, but DevOps engineers also need expertise in infrastructure-as-code (IaC) tools like Ansible and Terraform.

3. Collaboration: DevOps engineers work closely with both development and operations teams, emphasizing teamwork, whereas software engineers may work more independently or in smaller coding teams.

One point that resonated with me was how DevOps integrates continuous feedback loops into the development process, improving software quality and delivery speed.

Personal Reflection

Reading this article clarified the complementary nature of these fields. I’ve always enjoyed problem-solving and creating efficient solutions, which aligns with the goals of both software engineering and DevOps. However, DevOps’s focus on automation and system-level thinking piqued my curiosity, especially since I’ve been exploring tools like GitHub Actions in my personal projects.

This resource also reinforced the idea that adaptability is crucial in tech. Whether I choose software engineering or DevOps, learning skills from both domains will make me a more versatile professional. For example, I plan to experiment with IaC tools and practice creating CI/CD pipelines in my future projects.

Final Thoughts

Choosing between DevOps and software engineering is not just about job titles it’s about aligning your strengths and interests with industry needs. This exploration has helped me better understand what excites me about each field, and I feel more confident about preparing for either path.

For anyone considering a similar career decision, I highly recommend the TechTarget article. It’s a great resource for breaking down complex topics and understanding how different roles fit into the broader tech ecosystem.

Resouces:

https://www.gsdcouncil.org/blogs/devops-engineer-vs-software-engineer

https://www.techtarget.com/searchsoftwarequality/tip/Developer-vs-DevOps-engineer-similarities-and-differences

From the blog CS@Worcester – function & form by Nathan Bui and used with permission of the author. All other rights reserved by the author.

Since we’re diving deeper into web development, understanding how the frontend and backend work together is a must. It might sound like a techy tug-of-war, but it’s actually a smooth partnership—thanks to APIs (Application Programming Interfaces). Here’s how the magic happens, dumbing down.

The Frontend: The Face of Your App

The frontend is what users see and interact with. It’s all about the visuals and user experience. Imagine buttons, forms, and animations—that’s the frontend at work. Developers usually use HTML, CSS, and JavaScript frameworks like React or Angular to build this.

But here’s the kicker: the frontend is mostly clueless. It can show pretty pages, but it needs help to fetch or save data. That’s where the backend steps in.

The Backend: The Brain of Your App

The backend is like the brain. It’s where the logic, data processing, and database interaction happen. Built with tools like Node.js, Python, or Java, the backend handles all the “boring” stuff the user doesn’t see, like authenticating a login or storing a comment.

The frontend and backend don’t just shout at each other directly—they use an API to chat.

The API: Their Translator

The API is the middleman that helps the frontend and backend understand each other. Think of it as a menu at a restaurant(you would know if you read my previous entries). The frontend (the customer) picks something from the menu and places an order. The backend (the kitchen) cooks it up and sends it back. The API defines the rules of this exchange, so everyone’s on the same page.

Here’s how this plays out in real life:

1. Frontend Sends a Request: The user clicks a button to log in. The frontend sends an HTTP request (usually via POST) with the user’s credentials to the backend API at something like /api/login.
2. Backend Does Its Thing: The backend gets the request, checks if the credentials are valid, and prepares a response—like a token if the login is successful.
3. Backend Responds: The backend sends the token (or an error message) back to the frontend in JSON format.
4. Frontend Updates the UI: If the login worked, the frontend can now display the user’s dashboard. If not, it’ll show an error message like, “Try again, champ.”

Why This Connection Matters

APIs keep the frontend and backend loosely connected, so they can evolve separately. For example, you can upgrade your UI (frontend) without messing with your database logic (backend). Plus, APIs make your app’s backend reusable, other apps can connect to it too.

TL;DR

The frontend is the face, the backend is the brain, and the API is their translator. Together, they create the seamless apps we use daily. So next time you log in, search, or post, know that there’s a whole tech orchestra working behind the scenes. And now, you kind of know how it plays its tune!

From the blog CS@Worcester – Anairdo's WSU Computer Science Blog by anairdoduri and used with permission of the author. All other rights reserved by the author.

When I started studying computer science, I was unsure of what I wanted to do. As I learned, software development felt right for me, but that also asks another question, front end or back end? Initially, the front end seemed right for me, not for any particular reason other than working on the website felt better. However, after learning about both the back end and the front end, I am unsure now. 

In this blog post, Lane Wagner talks about their experience with front end development. They say that growing up, they wanted to be good at drawing, so that carried over into their computer science career. When they were working with front end things, they noticed that they focused their time on tweaking CSS, code for formatting the website, and it would always look bad anyways. They then decided that they wanted to become a back end developer instead, and talked about some other factors that affected their decision. These factors ranged from a number of things, such as pay and language preference, but the one that stuck out to me the most was feedback. They say that as a back end developer, you build code that is used by everyone, code like REST APIs, CLIs, and databases. This allows you to get feedback back from them in a way that is more constructive than if it was front end code, like UI. This lets you learn and improve.

After reading Wagner’s post, and reflecting on what I learned in class, I would also probably swing towards back end development too. The reason why I thought front end development would be better for me was because I am more artistic in a way. I also have a communication minor, so it would be a good way to combine the two. However, after learning both back end and front end, back end seems better to work with. The front end felt very convoluted to me, while the back end felt more seamless and streamlined. Maybe that was due to the fact that we spent more time learning the back end and playing around with it than the front end. Regardless, I would still love to learn more about both. I am still young, so learning both and maybe even working with both would help me choose which would be a better fit for me. But for now, back end development may be the better fit.

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

RESTful APIs are a common and standard structure used to develop software applications. Lately in class we have been delving into how these APIs work using Thea’s Pantry as an example. I found this blog that gives a concise and easy to understand explanation of REST works. He gives a brief overview of what REST stands for and then explains its purpose. It used to make data transfer between client and server easier and more encapsulated. One of the points that was interesting to me and made a connection to what we learned in class about coding principles. The principle of encapsulation and keeping things as independent as possible. Trying to keep the server and client as independent as possible to make scalability and maintenance more efficient. The REST API serves as an interface between client servers that serves to communicate for them so they don’t have to.

It then goes into more detail about resources and URLs and return formats. It was also interesting to me that return formats could be more than JSON, the example they used was XML. You just have to specify, but I don’t know a reason why you wouldn’t use JSON. The Reason I chose this blog is because it is a simple explanation of what REST API is. For me personally, APIs can be kind of hard to understand, but this blog explains in a way that makes it easy to understand. The picture was a big help. Other than that I don’t really have anything to say. 

https://medium.com/@MakeComputerScienceGreatAgain/understanding-rest-api-a-comprehensive-guide-52fc10f6c9ed

From the blog CS@Worcester – Code Craft by Kyle Tucker and used with permission of the author. All other rights reserved by the author.

Link to blog: https://dzone.com/articles/java-rest-api-frameworks-1

In class, we’ve been covering REST APIs and how to use certain call methods such as GET, POST, PUT, and DELETE. Before class, I had heard of REST APIs but never had any understanding of what they were, or how to interact with them. I figured I would dive deeper into other Java REST APIs. The article Java REST API Frameworks by Farith Jose Heras García lists some REST APIs along with their advantages and disadvantages.

García begins with a simple introduction to Java REST APIs and what they do, specifically how they enable communication between applications and other software, and make the passing of data easier. Each API on the list includes pros and cons, and then a CRUD (create, read, update, and delete) example using the API. 

First on the list is the wildly popular Spring Boot. According to García, some of the benefits of Spring Boot are that it is easy to use and set up, has a lot of built-in support, and has a large library of plugins and modules. The cons are that beginners might struggle to understand it, and it might be too much for smaller projects and better for larger projects instead.

Second on the list is Jersey. Jersey is simple, ideal for microservices, and also has a decent-sized library. However, García considers it slow and difficult to debug.

Third on the list is Play Framework. It’s lightweight and flexible, high performance, and also offers a library of plugins. It’s updated and designed for modern Java applications, as it works with Java 8 and Scala. Unfortunately, it has a tough learning curve and debugging can be a challenge.

The final on the list is Vert.x. It is lightweight, flexible, and has high-performance, and also supports JavaScript. The cons are that it is difficult to debug and might be hard to understand for a first-time user.

I selected this resource because it is an article that is a good reference for an updated list of Java REST APIs currently in use. It gets the point across for each item, whilst being a short enough read to be a good refresher for those unfamiliar with the information. It’s mainly beneficial for choosing which REST API to use with your project or application.

I found this to be a solid article for learning a little bit about Java REST APIs and how to choose them. For example, I did not know that Spring Boot is too heavy for smaller applications. The formatting was simple, and it’s pretty interesting to see the frameworks in action with the CRUD code examples García provided. Choosing the right REST API framework for your project’s needs is very important since many factors can go into such a decision (size, libraries, and easy learning curve). I hope to apply this to projects of my own and perhaps jobs where REST APIs are needed.

From the blog CS@Worcester – Josh's Coding Journey by joshuafife and used with permission of the author. All other rights reserved by the author.

As I become a more knowledgeable developer, I hear the term ‘software framework’ being used more frequently. In my research, I’ve seen an increased interest in frameworks such as Angular and React. To understand what these are, I must first define what is a software framework.

In the article What is a Framework? Software Frameworks Definition, written by Joel Olawanle, walks through a general definition of software frameworks, comments on how they may be applied, and how they differ. Olawanle defines a framework as such, “…is a structure that you can use to build software. It acts as a foundation so you don’t have to deal with creating unnecessary extra logic from scratch.”(Olawanle). Supposing a framework is implemented correctly, developers will save time allowing them to start the project earlier. Additionally, the foundation it provides will not be prone to human error. If the components of a framework are implemented from scratch, then there could be errors that would be much more difficult to fix further in development. Since frameworks can be modified, there is less of a reason to implement their functionality from scratch.

Olawanle expands his definition to other aspects of software development. Before reading this article, I understood that there were both frontend and backend frameworks, but I was surprised to learn that mobile applications and data sciences have their respective frameworks. While reading Olawanle’s article, I noticed a framework I used a few years ago, that being Bootstrap. This qualifies as a software framework as it gathers files needed for a functioning website (.html, . css, and .js) into one structure. This allows the developer to easily make their website without having to build this structure. Angular and React both are classified as Frontend frameworks. Both of these are used for creating interfaces for websites, but each has its unique components. React can use JavaScript to create HTML and CSS files, meanwhile Angular has dependency injection allowing it to more freely communicate with other applications. Each of these creates a specialized purpose for the framework. 

Depending on where a developer is working (front end, back end, etc), there will be a framework that can create a strong foundation for their code. Before selecting their framework, the developer must weigh the tradeoffs between the various frameworks and consider which would support their project principles the most. Using a framework in this scenario would save time and reduce any human error manually implementing these components introduce. In my experience with Theas’ Pantry, the backend does not use any framework listed within Olawanle’s article. After reviewing the documentation, it seems as if the back end would not support these listed frameworks as they are not directly language-compatible. This means more time and resources would be invested into implementing the framework, than potentially implementing components of such individually. Frameworks provide a strong starting point for development teams, depending on the design choices frameworks may be incompatible with certain projects.

Link to Article:

https://www.freecodecamp.org/news/what-is-a-framework-software-frameworks-definition/

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

Communication with those who help construct it or those who will use it is an essential component of any project. Software documentation serves both these ends, as it informs anyone approaching the project of topics such as the requirements used to run said software, instructions, and myriad other facets of the project. Documentation is created for those interested in the specified software/project. The Swimm Team, in their article What is Software Documentation? Types, tools, and best practices, list two types of documentation. These are external and internal documentation.

External documentation seeks to explain all aspects of the software that are not locally accessed. Most of this documentation involves user interaction. This is seen through End-User documentation, which provides the user with instructions on using the software, or through Just-In-Time Documentation, which guides the user while the program executes. A more technical piece of documentation, API documentation, is also considered external. Although most users may not directly interact with the API, this type of documentation is targeted towards developers who may want to expand the API functionality or use it in their projects. Due to the accessibility of external functions, its documentation must be equally accessible to its audience. A level of abstraction must be provided to reach this goal, as uninformed users do not need to understand how the internal systems of the software function, but rather they must learn how to interact with it.

Internal documentation refers to everything ‘behind the scenes’ so to speak. Contrary to external documentation, this documentation is less accessible, meaning it can go into detail on how the systems of the specified software work. Due to this complexity, it serves as a great introduction to the project and can be used to onboard new developers. Internal documentation ranges from information regarding the development cycle of the software, as seen through scheduling documentation,  to design choices seen throughout, which can be found in Software design documents. During the development process, software engineers can refer to internal documentation to ensure their contributions follow the team’s vision for the software.

My experience with software documentation has been limited up until this year. My most recent experience with documentation was through the HFOSS project Theas’ Pantry. Within this project, there was API documentation, available through a .yaml file, which listed all functions and associated code with all API calls. Additionally, there was indirect documentation offered through activities introducing onboarding developers onto the project. Each of these activities introduced a broad topic, such as software architecture, which then transitioned into how it’s applied to Theas’ Pantry. This untraditional form of documentation allows the onboarding developer to interact with the components in a microcosm before they apply their knowledge on the project. Documentation is a vital component of software development. Without supporting texts such as this, clients interested in the project would be met with inaccessibility, and onboarding (in addition to current) developers may not understand the project as a whole which could jeopardize the production of such. 

Link to Article:

https://swimm.io/learn/software-documentation/what-is-software-documentation-types-tools-and-best-practices

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