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.

In class after learning about a few select HTTP response codes, I wanted to look into the whole library of possible codes to get a better understanding of how website calls work and the potential errors that come with them. The blog I chose to read from gave a brief introduction to why knowing the meaning of the response codes is important for managing or using a website. Before going into the specific definitions of each code, the author states the main takeaways at the beginning of the article which helps the reader know what to look out for as they read ahead.

The codes are representations of the types of responses between the web server and the browser. Every time you use a new URL an HTTP code is generated. The author goes on to explain how making sure you have successful HTTP codes is a good way to promote a website because search engines use the HTTP response codes to determine if that URL will show up as a result.

Next is the part of the article that shows how the first of the three digits are grouped and defined, which I didn’t know and is helpful to know. Some that we didn’t go over in class was 100 codes that are for Informational responses and 300 for Redirection. There is then a reference table provided that gives the corresponding code and definition for each code. The author then goes into more detail about how search engines use these codes to determine what pages get recommended to users.

I think that for myself and how I tend to learn best is by looking up libraries of every possible response/function/use for something and deepening my understanding of a topic and knowing how it works and why it was made that certain way. It will also be helpful as both a developer and a user because now when I see an HTTP response code, I will know what it means and what I would need to do to fix or get around the problem. I also learned how important HTTP response codes are for increasing your website traffic and another reason to have efficient web code for something that I wouldn’t have thought of. Doing outside of class and self-directed research on class topics is very helpful to connect different topics together as well as how they relate to work that is done in the field

Common HTTP Response Codes Explained – Neil Patel

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

The blog post I’ve chosen is all about PlantUML diagrams and how they can be used in ways to help your coding. The author writes about why diagrams can be useful for seeing things visually in a text heavy environment like coding is. There are many advantages to representing code in a diagram. Making the program abstract and only focusing on the process of how each thing should work with the others helps to focus on concepts rather than the implementation and actual workings of the code. There are also many types of diagrams, such as sequence diagrams that show what events take place over time, a use case diagram that shows what different levels of users are able to do, class diagrams that detail different objects’ construction, activity diagrams that can show workflow, and others. PlantUML is able to be used in many different ways for many different scenarios. There are sometimes problems that PlantUML cannot solve in the most elegant way, as the author describes, but there are alternatives and some problems that PlantUML was not designed to solve.

I think this blog was helpful to read through and see just how versatile PlantUML diagrams can be after learning about how to make them in class. Another benefit to diagrams that the blog didn’t go over, but we did in class was being able to find potential problems in the code before you even type anything which can save a lot of time. I think that using UML diagrams more often can help me with coding as having a diagram that gives me a top-down view would be helpful to look at instead of scrolling through a wall of text to find what I need to do next or how I can improve my code. I sometimes find that I can overcomplicate some sections of my code and having a written out simplified plan to look back at will help me code with more focus and also help with encapsulation which I don’t do as often as I should.

After reading this blog I will be more aware of what situations could be helped with a PlantUML diagram and make one to keep me focused on the structure and entire scope of the program. There are also ways to use diagrams in order to show processes that I haven’t used yet or have talked about in other classes which could be a good tool to use in the future to explain and show complex abstract processes.

PlantUML Diagrams – Matt Hayes

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

As the first blog post, and naturally occurring when at the start of my CS-343 class, I had a hard time picking a topic. In class we haven’t gone over many new concepts, but my professor did mention during a topic review that there are other options from inheritance that are able to do very similar functions. Piquing my interest, I wanted to look into inheritance itself and what other people thought of it and compare it to my experience coding programs using inheritance.

The blog post I chose started with an introduction about how inheritance is taught in a way that doesn’t give students the best grasp at how to implement some of the more niche situations or real-world cases where inheritance would be the most efficient method. Something that the blog mentioned that has been something that as a student I have never really come across, is deciding when a certain method, in this case inheritance, is the best way to solve a problem. Usually with assignments, the method is already predetermined, and the implementation is what you are graded on, or because of the limited subjects covered, the intended method is easy to figure out.

The author then goes into the two main problems that inheritance has, the complex syntax and the complexity of the problem inheritance is best suited to. Inheritance has it’s own syntax that is new and you have to learn but it also gets difficult because the new context of the code now has new rules to it that need to be considered such as precedence, overriding, and variable types. The other problem is that cases where inheritance would be the best implementation are problems that have a reasonable amount of complexity. There needs to be two classes of objects that have a good deal of similarity between them but also be different enough and have a good amount of shared code to where you would not want them to be two separate classes. 

Reading this blog as well as reviewing inheritance in class has shown me that while I know the concepts and am able to write a program that utilizes inheritance, my experience with all of the special cases and interactions is not complete. The blog was more catered to teachers but as a student I also found it to be helpful. The blog doesn’t offer much in terms of a deeper look into the topic or language specific examples, but having learned more about it’s complexity I will be sure to look at other resources that more thoroughly and meticulously go over the nuances of inheritance so that I can feel confident in implementing it in any program where it would be a proper fit. I think it’s always good to try and fully understand a topic especially when you think you know everything about a topic and you run into a roadblock. 

Teaching Inheritance – Ada Developers Academy

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