Through my past couple blogs of Object Oriented Programming, REST APIs, and frameworks, I often came across the word “documentation” but commonly overthought it and didn’t do any more investigating into it. With that being said, I came across this blog 9 Software Documentation Best Practices + Real Examples and I feel a lot more comfortable with documentation as a whole. https://www.atlassian.com/blog/loom/software-documentation-best-practices

Imagine, you and your developing team are coding away on an application, but then an error appears, by which no one present knows how to solve it.

To solve this error, your options are:

1. Slack threads
2. Stack Overflow
3. Emails back and fourth 
4. Documentation 

The most promising answer of these options are documentation. With great documentation, you will get a clear precise solution to the problem you are facing. 

Now, what exactly is documentation? Documentation is written information that clearly explains the program’s structure, functionality, and when/how to use it; should be used as a guide or as a reference pointer for developers. If the documentation is done right, it reduces friction, boosts productivity, and helps the user understand the code from all angles due to the information of processes, functionalities, and solutions.

With so many benefits, documentation should be at the forefront of software developing teams, but unfortunately, it often gets overlooked. One of the main reasons for this is because documentation can go outdated very quickly. 

That being stated, here are nine ways to make sure your documentation will always be great:

1. Know your target audience
   1. General Audience (surface level) vs Developers (technical)
2. Keep it user-friendly
   1. Having a table of contents with clear headings can make it a lot more easier to find what the user is looking for
3. Use version control
   1. By doing this, you will be able to see all the latest updates
4. Incorporate visuals
   1. Some people are visual learners, who work better off of a video, photo and/or diagram (within reason)
5. Adopt a documentation style guide
   1. Consistent styling will make it easier for the user when going through each documentation type from said releasers (writers/developers)
6. Update regularly
   1. By doing this, your documentation will align with the latest software functionality
7. Encourage collaborative documentation
   1. Working together in person or remotely 
   2. Always good to have a peer’s input
8. Provide troubleshooting and FAQs
   1. This enables users to find solutions for common issues very effectively
9. Use documentation templates
   1. This will give a great start to all coming contributors of the documentation 

Overall, I really enjoyed this article and its purpose of making software documentation better. Furthermore, it mentioned how Google and Microsoft all stick to the same consistent documentation perspectively, which opened my eyes of how important consistency is in documentation within a company. Along with this, before “jumping” into something new, it will definitely be worth it to go over the documentation. Understanding and referencing any documentation is a skill.

From the blog CS@Worcester – Programming with Santiago by Santiago Donadio and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Hello, for this quarter’s blog I read “The Day My Role-Based REST API Design Collapsed (and What I Learned)” by Sidharth Devaraj. Per the title, the blog talks about REST APIs, specifically Sidharth’s experience with them when he was new to backend development, and his reflections on a key mistake he made when designing his first REST API. To quickly summarize what that is; per GeeksForGeeks a rest API “…is a type of API (Application Programming Interface) that allows communication between different systems over the internet. REST APIs work by sending requests and receiving responses, typically in JSON format, between the client and server”. Following the theme of my previous blog, this is a topic pertinent to what we have recently been doing in class, and sometJhing I would like to see a human perspective on to gain insight about how I may utilize it in the future. 

Sidharth starts by explaining that he needed to make an API for an application he was working on. He mentions that when he was initially planning things out, he decided that he wanted to focus on keeping things organized and easy to understand. To accomplish this, his API was categorized into something that he, at the time, thought was pretty smart: user roles. These different roles would then act as routes for items to be used by those roles, i.e. /admin/… would host administrative objects, and /customer/… would host items used by a customer. At first glance this seems like it could be a pretty good idea, and Sidharth was pretty happy with what he thought up. However, he didn’t account for a crucial situation; what if both admins and customers both needed to interact with the same resources? It simply wouldn’t be feasible. The more resources created, the more issues arise. He ends his blog by pointing to the importance of a key design principle of REST: focus on resources, not roles. 

At first I thought this was a pretty bad mistake. If he had only thought a bit about how a role can’t be used by two different groups, he wouldn’t have made it in the first place. But then I thought about something; what if when initially building the application, none of his resources were needed by the two different groups? If he was testing things, in that situation he would never run into any issues, and wouldn’t be made aware of the flaws of his design. Only once the API started scaling did it become prevalent. I initially thought the blog was a pretty good read, but nothing special. It was more or less just “follow the design principles” without much more substance than that. However, reading into it a bit more it also touches on the importance of future-proofing your designs. Initially, Sidharth’s API worked great. Had his requirements not changed, he would have accomplished his goal of keeping it organized and easy to understand. However, as those requirements changed, new issues that weren’t present before arose. Scaling your work isn’t something I really think about much, when working on projects I really only think about how they can accomplish the present goal. But, in a professional environment, requirements will never be static, and this is something I really should get into my head. This blog definitely reminded me of that. 

From the blog Joshua's Blog by Joshua D. and used with permission of the author. All other rights reserved by the author.

Code Refactoring and why should refactor your code by Lazar Nikolov

For this blog post, I chose to write about Code Refactoring. Nikolov starts off by expressing the idea that software does not expire, but it rots over time. The program continues to work, but as we add quick fixes, messy code, and shortcuts, it begins to become harder to work with. What is refactoring? In simple terms, refactoring is the process of cleaning and improving code without changing what the program actually does. To do this we must find code smells and technical debt and then begin removing them.

Code smells are not bugs that causes problems to your program. Instead they are warning signs that something is wrong with the design even though the code runs. Some examples of this can be having very large functions that try to do more than it should, confusing names, and complex logic that is hard to follow. Code written this way is often closely tied together. This could cause changing one small thing to break another part.

Technical debt is what happens when we choose the fast and easier solution like a shortcut to fixing a problem. This happens when we’re rushing to meet a deadline or don’t have coding standards. As a result we pay the price later with extra work since the code is hard to fix and improve on.

When should you refactor your code? Some signs are repeated code, having many bugs, or you are unable to add a new feature since the existing code is hard to work with. This relates to a term we’ve learned in class known as DRY (Don’t Repeat Yourself) and AHA (Avoid Hasty Abstractions). DRY says we should not repeat the same logic many times in our code. AHA reminds us we shouldn’t create abstractions early on.

This blog made me realize how much I relate to this topic. As someone who can say they often procrastinate and usually does assignments at the last minute. I’ll write quick code that “just works” so I can finish my assignments. I rarely think about how I can improve or add to it later. But I now understand that these shortcuts will definitely turn into technical debt. Moving forward, I’m going to watch for code smells more often as I work on projects. My goal is to write more optimized, cleaner code that would be better in the long run.

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

In class, we have continued the usage of REST API, and we will only continue to use it. Through homework assignments and class activities, I’ve gotten more comfortable with REST API, but will need to have a good understanding of it as it is a vital part of my capstone project next semester. I found this blog of Stack Overflow that listed some best practices for REST API design that I was previously unaware of or did not have full knowledge of. 

Nest Endpoints That Contain Associated Info

If your database has objects that contain other objects, it is a good idea to reflect that in the endpoints. An example from guestInfoBackend would be “/guests/:uuid/assistance/”. This URI is used to access the “assistance” object inside a specific guest. But note that having multi-level nests can get out of hand. A bad example would be having an endpoint that looks like: /articles/:articleId/comments/:commentId/author. It is better to use the URI for the specific user within the JSON response as follows: “author”: “/users/:userId”.

Return HTTP Response Codes Indicating What Kind Of Error Occurred

HTTP response codes help to eliminate confusion when an occurs. Response codes give the API maintainers enough information to understand the problem that has occurred. The blog also showed some other common codes that were not discussed in class:

• 401 Unauthorized – user isn’t not authorized to access a resource; usually returns when the user isn’t authenticated.
• 403 Forbidden – user is authenticated, but not allowed to access a resource.
• 502 Bad Gateway – invalid response from an upstream server.
• 503 Service Unavailable – something unexpected happened on the server side; this could be anything from server overload to some parts of the system failing.

Messages also need to be attached to response codes so that maintainers have enough information to troubleshoot the issue, and that attackers can’t use any of the error content to launch attacks.

Maintain Good Security Practices

The communication between client and server should be private. A good way to secure your REST API is by loading an SSL/TLS certificate onto the server. They are very low cost or even free to use, so it is a no-brainer to strengthen security. It is also a good idea to apply the principle of least privilege. Each user should have role checks or more granular permissions. The admin should not have an issue adding and/or removing permissions and roles from users.

Version APIs

In order to prevent clients from being broken while making changes to the API, different versions of the API should be available. This way, old endpoints can be phased out instead of forcing everyone to switch over to the new version at the same time. This is important for public APIs and is how most apps today handle making changes.

Source

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

From the blog CS@Worcester – Blog del William by William Cordor and used with permission of the author. All other rights reserved by the author.