5 terms to know as a technical writer [part 3]

What is a query parameter?

When you type out a URL in your browser it leads you to a webpage. Also sometimes unique information from the user requesting the page needs to be sent to the web page or server.

For example, let's say you visit a website that shows you a list of movies. Let's say the URL pointing to this website is movies.com. On such a website we will expect a huge list of movies and scrolling through to find a specific movie will be a painful process.

So let's say this website has a search box, where you can type out the name of the movie you will like to search and a list of suggestions is returned to you. When you fill out the search box this information needs to be sent back to the server responsible for the webpage. One way the website can send back your search query is to append it to the URL as a query parameter. This usually looks something like this movie.com?title=avengers.

In the above URL, we took our initial URL movie.com and appended ?title=avengers to it. Most web servers are set up to understand that the = pair after the ? is a special combo, of an expected key in this case title and a value being what the user will like to search for.

This is then relayed to the web application to interpret as "A user just filled out the value of title as avengers what do you want to do?" The web application knows to send back movies with a title similar to avengers. Also, you can pass as many query parameters as the web application allows. For example, to query by the "title", "year", and "rating", this would be movie.com?title=avenger&year=2020&rating=3. Each complete query is separated by the & symbol.

In summary instead of getting the same content over and over when you visit a website, query parameters allow you to tweak the output based on your input.

What is a Path Parameter?

Path Parameters aim to achieve the same thing as query parameters, in that it allows you to send information back to a web application by appending them to the URL. The main difference between a path parameter and a query parameter is in the structure of the resulting URL. For example, to search for a movie with the title avengers, the URL will be movie.com?title=avengers in query parameter form but movie.com/title/avengers in path parameter form.

As you can see path parameters uses the / symbol to pass data to the web application. This makes it look a lot more natural and similar to the URLs we are used to.

I should mention that there are other ways to pass data to the server without modifying the URL. Most online forms use the POST method to submit data to the server. This involves the use of a different URL so the user won't notice a change in the original URL in their browser's URL bar.

What exactly is a request?

There are loads of computers hooked up to the internet known as servers. The job of these computers is to serve up data and perform actions when a user asks for them. The process of asking for them is known as making a request. There are different and many ways to make a request to a server and the one you use sometimes depends on the kind of action you are trying to perform.

For example, by just visiting a URL in your browser you are performing a request. So when you type in facebook.com in your browser you have performed a request, similarly, when you fill out a form you perform a request but the structure of this request is a bit different from the former.

In software development land you will hear phrases such as "the frontend made a request to the server". Humans are not the only ones who make requests, computers can make requests to other computers as well. For example, some developers separate the user interface of an application from the backend of the same software, and for both parts of the software to communicate the frontend must send and request data from the backend.

You can also use tools such as Postman to make requests to APIs.

What is an endpoint?

I will try my best to explain this one. Honestly, this term has been thrown around soo many times. APIs represent every component involved in the process of sending and fetching data from a server, an endpoint is one of such components, specifically the exact URL you hit to perform a specific action.

So for example let's say you need to hit the URL movie.com/latest to get back the list of latest movies and movie.com/old to get the list of old movies. As you can see the base URL is movie.com in both examples. In this case, the endpoints are latest and /old. So you will hear software professionals ask one another "what is the endpoint for getting the list of subscribers?" and get back a response like "oh its /subscribers"

What is this semver thingy?

Versioning!!, Let's talk about versioning. This is a key part of any constantly evolving piece of software. With versioning, software teams can tag each stage of the software evolution using a versioning system and one of such schemes is Semver.

Semver fully expands to Semantic versioning. Anything to do with semantics is meant to denote structure. Here it refers to the use of a pattern to track software changes.

Any piece of software goes through three types of changes or growth: Fixes for broken parts of the software. Changes to improve the software And updates that lead to the software being very different from an earlier version

Whenever an end-user updates the version of the software they are using, they need to know if it will function as it used to or if major changes were made. One way to capture that is by using Semver versioning. In the case of Semver versioning, a 3 part numeric structure is used in the versioning structure, something like this Major.Minor.Patch eg: 1.2.3

The leading number is the Major index, this is increased if the changes made to the software are not compatible with a previous version of the software. This means the end-user will not be able to merge the changes into their existing software.

The Second part is increased when the changes made affect or improve the current software and a user updating to that version will not lead to incompatibility issues. This part of the Semver versioning scheme is known as the Minor index.

In situations where a feature has been fixed, because it's not working as it should, the last part of the versioning scheme is increased once the fix is applied. This part of the Semver versioning scheme is known as the Patch index

You can learn more about Semver and its usefulness in software development from its official website. Also, if you will like to know when I post content like this, consider joining my newsletter