DEV Community: Bruno da Silva

Part II - Summary and Impressions on the Book “Tidy First? A Personal Exercise in Empirical Software Design” by Kent Beck

Bruno da Silva — Tue, 10 Feb 2026 01:33:22 +0000

Part II - What is The Right Timing for Tydings?

This is the second part of the article Summary and Impressions on the Book “Tidy First? A Personal Exercise in Empirical Software Design” by Kent Beck. Please, you’re invited to read Part I, if you haven’t yet 🙂

Ok, so what is The Right Timing for Tydings?

This is a very interesting question in so many ways. Perhaps, this is interesting because there’s no single answer that can be generalizable. Actually, there’s even a question on whether tidyings should be applied at all. So, assuming the pull request model, here’s the puzzle:

I create a PR with my behavior changes mixed up with my tidyings.
Reviewers complain that my PRs are too long or going out of scope.
I separate the tidyings into their own PRs, either before (more likely) or after the PR with behavior changes.
Reviewers complain that the tidying PRs are pointless (or time pressure prevents my PRs from being reviewed).
Go back to 1.

Of course, the problem above will depend on other factors too, such as the size of the PR, review latency, different moments in the release cycle, etc. But if you’re tidying the code, the changes do need to go somewhere. There’s no single solution that will guarantee steps 2 or 4 are not going to happen, but there are some practices that might help in reducing them or avoiding them to some extent.

From the book, the short version of the recommendation is: tydings go in their own PRs, with as few tydings per PR as possible – option 3 above, but this is easier said than done.

What to consider then?

The book breaks this down a bit more as a trade-off analysis that’ll, of course, depend on context and engineer’s intuition. Watch for:

Batch Size: amount of tidying per batch (or PR).
- Collisions: the more tidyings per batch, the longer the delay before integrating, and the greater the chance that a tidying collides with work someone else is doing.
  - This becomes even more critical when the codebase is super large with hundreds of contributors.
- Interactions: the chance of a tidying batch accidentally changing behavior rises with the number of tidyings in the batch. And likewise, merge costs rise dramatically when we have an interaction.
- Speculation: The more tidyings per batch, the more we are prone to tidying unnecessarily.
Time put into a tidying batch: a good rule of thumb to measure the batch size is to look at how long your tidying is taking. It’s supposed to take a few minutes up to an hour. If it takes longer than an hour then it might mean you’ve lost track of the minimum set of structure changes needed to enable your desired behavior change.

Unfortunately, in many organizations, the cost of getting a single change through review and deployment is high, which kind of forces engineers to work on fewer batches, which in turn forces the team to work on bigger batches – the anti-pattern of bigger and less frequent batches. That goes back to the basics of Continuous Integration (or why software integration became ‘continuous integration').

All in all, considering the code review PR-based model, if we want to make tidyings low cost, which thus decreases the cost of making behavior changes, the best approach is to work on reducing the cost of code reviews (or even eliminating the need for it, but that’s something for another article).

Also, adding another piece not mentioned in the book, orthogonal to all that is the presence of a good test suite. When changes are “guarded” by a good set of tests which developers can rely on, it is the most rewarding investment a team can make, in my opinion. Besides code review, the presence of tests will certainly contribute to increasing developers and reviewers confidence about the changes in question, thus reducing friction on tidying (whether they’re mixed up with behavior changes or in separate PRs). And if they’re batched in separate PRs, and passing all tests, the need for code review is reduced (unless engineers do code reviews for other purposes such as knowledge distribution for instance).

Ok, those were considerations about tidying batch size and how long they take. But, what about how tangled tidyings usually get in the code changing process?

Separating tidyings in practice

In practice, naturally, while you’re working on a PR, you tend to make a sequence of mixed changes that involve tydings and behavior changes. That results in three options:

1. Ship it as is. This is impolite to reviewers and prone to errors, but it’s quick.

2. Untangle the tidyings and changes into separate PRs, or a sequence of PRs, or a sequence of commits in a single PR. This is more polite, but it can be a lot of work.

3. Discard your work in progress and start over, tidying first. This is more work, but it leaves a coherent chain of commits.

In summary, these options stem from deciding between ‘untangling’ the tidyings and work on them in separate PRs or not (just shipping them mixed with behavior changes), thus assuming you should tidy.

However, there’s still an important question to answer: Should I tidy at all? And if yes, when? Way later? Or right after I make the behavior changes? Or right before?

Never, Later, After, First?

Never: that’s basically the idea of ‘if it ain’t broke, don’t fix it.’ or ‘yes, there is a mess, but we consciously choose not to do anything about it as we’re not changing the behavior significantly anyways’’

Later: the tidying batch is big, and there’s a payoff, but it is not immediate. So, break up the big batch into smaller ones. Work on small tidying batches in between future behavior changes.

After: when the tidying batch is not big, waiting for later will make the work ‘more expensive,’ and when you won’t feel a sense of work completion if you don’t tidy after your behavior changes.

First: when it’s clear what to tidy and how, and the tidyings pay off immediately in terms of code and design comprehension and less expensive behavior changes.

And what’s the economic reasoning behind all that?

The Economics Reasoning

Behind all the alternatives listed above, there’s the concept of “cost” (or money). Kent applies two economic metaphors to when to do the tidyings. The first one is A Dollar Today > A Dollar Tomorrow – This is based on the notion that the money earned today is worth more next day (and as time goes by) because that allows you to invest it in exchange for some benefit (i.e., more money or some other benefit). You can read it as materializing a software change sooner is better when you can collect the benefits/profits of such a change sooner than later. So, this ties back to what we saw earlier.

Tidy After (or Later): If we can implement behavior changes that make us money now and tidy after, let’s then make money sooner and spend later – this gives us the flexibility to exercise a profit soon and the ability to invest it to make our today-dollar > tomorrow-dollar (and part of that investment can be a batch of tidyings later or not). However…
Tidy First: If the cost of tidying first + cost of behavior changes is still less than the cost of the behavior changes without tidying, then let’s go for it! There’s no point in ‘paying’ more for a tidying after or later if it can be done at a lower cost now.

And what if the opposite is true? The cost(tidying) + cost(behavior changes after tidying) > cost(behavior changes without tidying). Hmm… if you answer is “No, don’t tidy first, in this case, or don’t tidy at all.” then maybe you’re right. But maybe you’re not. Still, no straight answer, unfortunately. That leads us to the second economic-related concept posed by Kent and that is the concept of Options.

Without going into the details about the concept of Options in the finance domain, here you can assume that, as a software engineer, you may want to exercise an Option by investing time on tidying first based on the speculation (or I should say based on your best judgment call as an engineer) that your tidyings will enable profits (i.e., benefits) in the future. As in the finance domain, an Option comes at high risk (the risk of being wrong in your speculation or judgment call). For instance, even though when cost(tidying) + cost(behavior changes after tidying) > cost(behavior changes without tidying), you may still think that you can amortize the cost of tidying first over a series of behavior changes in the near future that can benefit from the tidyings.

If I was able to summarize well the two economic concepts (today-dollar > tomorrow-dollar & Options) then you probably realized at this point that those two strategies conflict at times. This means:

Earning money now (today-dollar over tomorrow-dollar) can reduce future options. This relates to the decisions of “Tidy After” or “Tidy Later” or maybe don’t even tidy at all.
However, perhaps, if you don’t earn money now (if you spend, instead), you may get a chance to exercise those future options. “Options tell us to spend money now to make more money later“. This relates to “Tidy First” and to possibly combine it with “Tidy After” and “Tidy Later” too. If the value of the options created is greater than the value lost by spending money sooner and with certainty than this path makes sense.

Too complicated? Hmm… Yes (at least it sounded complicated to me at first). However, I have found this theory good to frame my mind around this software design topic. I think it can help the thought process as a conceptual framework while engineers evolve software.

From the book, “software design has to reconcile the imperatives of ‘earn sooner/spend later’ and ‘create options, not things’.” And that’s what makes this economic dimension discussed in the book such an interesting topic – and no wonder why software design is such a simple topic at first, and yet a complicated matter at the same time.

Finally, this book is the first of a series that is in the works. Kent promised two other books following this one. Let’s wait and see.

Impressions on the Book “Tidy First? A Personal Exercise in Empirical Software Design” by Kent Beck

Bruno da Silva — Tue, 10 Feb 2026 01:05:14 +0000

First and foremost, it is good to see a well-known figure and book writer in our field writing a new book about something not everybody strives for every day – code quality. And it comes many many years after other similar books in the area, such as Refactoring by Fowler (1st edition from 1999) and Clean Code by Robert Martin (2008). So, even though the book does not open a completely new area, it still shows practitioners the motivation to look at code quality in the small with a magnifying glass, as we (at CQSE) do.

I divided this article into two parts based on the two most interesting dimensions I found in the book. In the first part, I summarize some key points from the book that relate directly to what we (at CQSE) praise daily – small moves that make developers’ lives easier. However, it is in the second part that lies the even more interesting dimension, in my opinion. There, I summarize the temporal and economic spin Kent provides in his book. The “First?” part of the title “Tidy First?” gives a hint of what it entails – What is the right time to tidy up the code? Tidy first? Before you make behavior-change modifications? Or right after behavior modifications? Later? Or never?

Part I - The Foundation: Small Moves that Make Developers’ Lives Easier

If you are wondering what exactly “tidying” is and whether it differs from “refactoring”, let’s then clarify it. The book defines "tidying" as a small, tiny refactoring. While refactoring is defined as changes to structure that don’t modify behavior, tidyings are “the cute, fuzzy, little refactorings that nobody could possibly hate on.” Moreover, Kent observes that “‘Refactoring’ took fatal damage when folks started using it to refer to long pauses in feature development. They even eliminated the ‘don’t change behavior’ clause, so refactoring could easily break the system.” Indeed, I have heard people refer to refactoring in many different ways, matching Kent’s observation. Probably, you have heard that too. So, whether it’s going to stick or not, here we are with another terminology – “Tidying.”

And here’s a list of tidyings presented in the book. Kent doesn’t go deep in exploring them. Some of them only take half a page, which is fine, since they’re not new.

Guard Clauses
Dead Code
Move Declaration and Initialization Together
Explaining Variables
Explaining Constants
Explicit Parameters
Chunk Statements
Extract Helper
One Pile
Explaining Comments
Delete Redundant Comments

Even though they are not new, I can see some reasons why Kent deserved time and effort on that part of the book. First, it makes the book self-contained. Second, it clearly and concretely expresses what the author means by tidyings being “cute, fuzzy, little refactorings” rather than just citing what’s in Fowler’s or Martin’s books otherwise.

Now, zooming out a bit, I liked the connection built between tidyings and the duo Coupling-and-Cohesion, since pretty much any refactoring (and tidying) revolves around these two, often interconnected, design properties.

The Duo Coupling-and-Cohesion is Key

Kent refers to Ed Yourdon and Larry Constantine’s work multiple times in different places in the book. Yourdon & Constantine laid the foundation for this notion of coupling and cohesion in software design in such a pragmatic way back in the 70s.

Coupling and Cohesion are really how your brain deals with complicated systems.

Cohesion Order (and Whether to Decouple)

It is about avoiding changing widely dispersed spots in the code. Reorder the code elements you need to change so they become adjacent (not only in the same source file but across different files and folders).

Moreover, why not just eliminate the coupling that leads to those changes in widely dispersed spots? Well...First, if you know how to do it, and if you can do it, go for it!

But note: cost(decoupling) + cost(change) < cost(coupling) + cost(change)

It may not be feasible, though, for various reasons:

Decoupling can be an intellectual stretch (you don’t know how to do it).

Decoupling can be a time/money stretch (you could do it, but you can’t afford to take that time just now).

Decoupling can be a relationship stretch (the team has taken as much change as it can handle right now).

If you're an experienced engineer or a software quality expert, you might be thinking “I know... this is not new.” But I bet a lot of engineers out there don’t think straight that way for various reasons (topic for another article).

I hope I’m not sounding overly passionate about this coupling-cohesion topic 🙂 but I have to say I’m biased since I read a lot about cohesion as it was my Ph.D. topic many years ago.

Coupling and Constantine’s Equivalence

If you think from the perspective that the goal of software design is to minimize the cost of software (i.e., the cost of owning and maintaining software), then we have to understand what such a cost means. Working in this field, we all know this is not hard to make sense of. However, I really liked the way Kent explains this as “Constantine’s Equivalence” which I summarize here.

The Constantine’s Equivalence is: cost(software) ~= cost(change)

Where cost(change) follows a power law distribution. What does that mean? That means a few big outliers (very high-cost changes) matter a lot even though they are just a few outliers. If you add them up (the sum of cost of big changes), they will outweigh the far more usual changes. In other words, “the most expensive behavior changes cost, together, far more than all the least expensive behavior changes put together.” Or put another way:

cost(change) ~= cost(big changes)

And what exactly makes the cost of such big changes highly expensive? You probably know the answer – big changes are not isolated in a single cohesive element in the design. They’re often propagated across different highly coupled spots. And that boils down to:

cost(software) ~= cost(change) ~= cost(big changes) ~= coupling

Or simply cost(software) ~= coupling

However, decoupling has its own cost, too (besides, of course, there will always be some coupling degree in any software). What are the tradeoffs? It all comes down to the second dimension of the book that addresses What is the right timing for tidying (or decoupling)? Or whether it should be done at all. In short, it depends on whether it’s worth paying the cost of coupling now if there’s a chance of making a profit out of it soon, or whether it’s worth paying the cost of DEcoupling now while reaping the benefits of doing it is even higher (even if benefits come later). Let’s expand on all that in Part II.

Product Manager vs. Product Owner [and the Product-minded Software Engineer]

Bruno da Silva — Sat, 20 Nov 2021 00:30:18 +0000

In this article, I clarify the differences and similarities between Product Manager and Product Owner. Also, I take the chance to briefly talk about the importance of the product mindset in software engineers.

All right, let's jump into the first part.

Product Manager vs. Product Owner

Product Owner (PO) is one of the process roles in Scrum. Scrum is a process framework for developing and sustaining complex products. Let's look at how Scrum defines the PO role:

A Product Owner orders the work for a complex problem into a Product Backlog.

Typically, only one person is playing the PO role at a time in a Scrum team. The concept of a "complex problem" is vaguely defined in the sentence above from the Scrum Guide and I think this is intentional since the Scrum framework can be applied to all sorts of problems. And they go on:

The Product Owner is accountable for maximizing the value of the product resulting from the work of the Scrum Team. How this is done may vary widely across organizations, Scrum Teams, and individuals.

The Product Owner is also accountable for effective Product Backlog management, which includes:

Developing and explicitly communicating the Product Goal;

Creating and clearly communicating Product Backlog items;

Ordering Product Backlog items; and,

Ensuring that the Product Backlog is transparent, visible and understood.

The Product Owner may do the above work or may delegate the responsibility to others. Regardless, the Product Owner remains accountable.

For Product Owners to succeed, the entire organization must respect their decisions. These decisions are visible in the content and ordering of the Product Backlog, and through the inspectable Increment at the Sprint Review.

The Product Owner is one person, not a committee. The Product Owner may represent the needs of many stakeholders in the Product Backlog. Those wanting to change the Product Backlog can do so by trying to convince the Product Owner.

In summary, as many people say, the PO is the voice of the stakeholder. The PO is supposed to bridge the gap between the problem domain and the rest of the Scrum team working on a solution. That's the only way they can maximize the value of the product (as the definition suggests).

Well... All of it is in the context of the Scrum framework. The PO role is a particular Scrum terminology. Strictly speaking, outside Scrum, people do not use this term very often. And my hypothesis is that his happens for two main reasons. First, there has been more emphasis on the backlog management and grooming pieces of the PO role rather than the "maximize the value of the product" piece of the PO responsibility. Second, in order to maximize the value of the product, people need to go way beyond the team backlog scope. And that's when the concept of Product Management comes into play.

Product management is a career, not just a role you play on a team. The product manager deeply understands both the business and the customer to identify the right opportunities to produce value -- Escaping the Build Trap by Melissa Perri.

Generally, a Product Manager talks to customers to understand their crucial pain points, gather requirements, and test ideas to further explore potential solutions. PMs may also collect and analyze telemetry data to draw conclusions about existing products and features. PMs also communicate "in different languages" with various people such as engineers, UI/UX designers, researchers, marketing, sales, etc. PMs create product roadmaps and manage backlog items together with engineering teams. PMs work with business and engineering counterparts to define metrics, analyze data, and assess whether the product is going in the right direction by delivering value to the organization. Another essential skill in PMs is the capacity to drive conversations and influence others without authority. Ultimately, PMs should keep the team focused on the why (Why are we building this product, and what outcome will it produce?).

The above paragraph summarizes some of the most important PM responsibilities, and there is probably more depending on the organization. As you may have noticed, these responsibilities associated with the product management job are not explicitly defined as the PO role in the Scrum framework. Indeed, PM is a full-time job, whereas PO is specifically a role in a Scrum team.

If you are a Product Manager and your team follows the Scrum framework, we can tell you play the PO role in the team. But not all PMs are POs, simply because not everyone follows the Scrum framework.

Here's the confusion now.

Hey, Bruno, I've heard someone saying they're a PO in a team that does not follow Scrum. They follow whatever agile practices they find applicable to their context. Are they mistakenly applying the terminology?

My short answer is Yes, they are applying the wrong terminology. As discussed, PO emerged as a Scrum term and with a scope clearly defined in the Scrum framework.

Bruno, in this new project, the other developers working with me will continue as developers while I volunteered to be a PO, since we don't have anyone else in the company to be a PO in this project and I know the domain well. Can I consider myself a PM, too?

Tricky question. Without much additional context, I'd say No, you're not a PM. In this case, you're a developer working temporarily as PO in a project. You may be a developer at times and switch to play the PO role at other times. Still, your job is not a full-time Product Manager. This experience may lead you to become a full-time PM, though.

All in all, we cannot control how people apply those terms in the field. At the end of the day, people are not committing a crime by calling PMs as POs and vice-versa. Moreover, some buzzwords come and go over time, and we never know to what extent practitioners will adhere to specific terms in the field. Some years from now, the chances are that new terms will apply to the Product Management area, and this article may even become obsolete. For now, you can consider the general term as PM, while PO is the specific terminology for the "product person" in the specific context of a Scrum team. That's also why you see Product Manager as the job title in many job ads when organizations look for "product people."

Well... And if you are a software engineer, and you want to stand out in the crowd and deliver significant value to your users, try to develop the product mindset in you.

The Product-minded Software Engineer

While you can simply define PMs as those responsible for defining the "what" and the "why" in software products, software engineers are sometimes defined as the deeply technical people that are specialized in hacking out solutions (the "how") to solve end-user problems. And this is not largely wrong. Many successful software engineers, in their careers, do not develop a product mindset that makes them connect well with the value proposition of the solutions they implement. However, more and more, the industry needs engineers capable of reducing the gap between the problem domain and the solution domain and understanding the impact of their solutions and fine-grained design decisions on the business as a whole.

This is what we call "Product-minded Software Engineers." These are engineers that work close to the product vision and give inputs to the roadmap. They also make an effort to understand why product decisions are made, how people use the product and often endeavor to actively make product decisions.

Throughout their career, product-minded engineers find more flexibility in either switching to a product management career or moving up on the engineering career ladder by showing the product-awareness capacity in their work. Whether in big tech-companies building world-class products or startups developing highly innovative ideas, product-minded engineers usually help organizations take teams to a new level of impact.

From a management perspective, these are the engineers you like to work with to shorten the gap between the problem and solution spaces and ultimately deliver value to users and businesses in a more productive fashion at a lower friction.

If you want to read more about product-minded engineers, check this article from an experienced ex-engineering manager at Uber.

If you want to discuss anything related to this content, please drop me a line on Twitter (@BrunoDaSilvaSE) or a comment below.

I welcome your feedback!

Building Your First React App with Hooks (and Git) (Part II)

Bruno da Silva — Thu, 16 Sep 2021 18:12:30 +0000

This tutorial is a continuation of the React tutorial Part I. If you haven't finished the previous one, I suggest you go back and complete that one first before jumping into this one.

The goal is to continue building our first React app, including now state handling, along with using Git and GitHub.

This article was initially created as a lab assignment in an intro to software engineering course I've taught at Cal Poly. A series of other articles has been published. I hope you follow along!

$$ 0 - Installing git (skip if you already have git installed)

Follow this link to install git according to your OS: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Run git --version to make sure it is installed.

1 - Creating a git repository

Here we'll initialize your app folder to be tracked by git. In the terminal, 'cd' to your React app folder and run git init in it. From now on, your project folder is locally tracked by Git.

Go to github.com and create a repository at GitHub. If it's your first time on GitHub, you'll need an account. Note 1: At this time, DO NOT check 'initialize this repository with a README' and DO NOT check 'Add .gitignore'. You can work on the readme and gitignore files for your repo later.

2 - Committing changes and pushing

Next, we'll commit our changes. If you're new to git, remember that there are files we never commit. For instance, the /node_modules folder of your app contains your local libs. Every developer collaborating in your project would have their own /node_modules folder managed when running their npm commands. So, we'll make sure the '/node_modules' folder is in our .gitignore file.

In the root of your app folder open this file '.gitignore' and check if there's this line:
/node_modules

If you're following this tutorial having done Part I already, you'll see the .gitignore file with this line already (it was created when you ran the npx create-react-app command from Part I). Otherwise, create the .gitignore file by yourself in the root folder and add that line.

This will make git ignore whatever you place in that file and never track what's in there.

To commit changes, we have to stage our files. So, first, stage everything in your app folder except the /node_modules (we already added it to our gitignore file). For instance, here's how you stage your /src folder:

git add src

Run git status to check what's staged and what's unstaged. Anytime you're lost, the git status command will be helpful.

Once everything is staged, you'll commit changes. Remember that, on git, we commit locally and, only after that we can push one or more commits to a remote repository (e.g., GitHub). It's a good practice to add a commit message to communicate what represents your code changes. Even if it's obvious, place a clear and concise message since, in general, these messages can be used to understand the history of code modifications and help maintenance activities.

git commit -m 'First commit of my react app'

Now we're almost ready to push changes to your remote GitHub repo. We need first to tell your local git repository that you have a remote host. Here's the command to do it (you'll also see these instructions on your GitHub repo page once you create the repo):

git remote add origin https://github.com/your-username/your-repo-name.git

This is the only time you have to run the git remote add command.

Now, locally in our git, we'll rename our 'master' (default) branch to 'main' with the following command (GitHub already recognizes 'main' as the default branch). As a side note: technically, this is not a required step, but ethically the best choice [1] [2] [3].

git branch -M main

Then, we'll call the actual push to GitHub:

git push -u origin main

Finally, you should be able to visit your GitHub repo online. Visit github.com/your-username/you-repo-name, and you will see your commit there.

To exercise one more useful command, on GitHub, edit the existing README.md file (or create a new one) following their web interface. If you've followed all the steps since Part I you should see a README file already pushed to GH. If for some reason you don't see one, you'll see a button "Create Readme." If there's a readme.md already in your root folder, you can click on that file and then edit it on GH interface to represent a change in the remote repo. Once you hit that button and edit or create a readme file, GitHub will generate a commit triggered by its web interface.

When you're done with it by either editing an existing readme file or creating a new one, you still won't have this commit/change in your local repo. So, go to the terminal and run git pull to bring the commit to your repo (remember that git pull executes a git fetch and a git merge at once). Now, the readme file is also local since you just synchronized your local repo with the remote repo.

3 - State (back to React)

So far, we're storing our character data in an array and passing it through as props. This is good to start, but imagine if we want to be able to delete an item from the array. With props, we have a one-way data flow, but with state we can update private data from a component.

You can think of state as any data that should be saved and modified without necessarily being added to a database - for example, adding and removing items from a shopping cart before confirming your purchase.

There are different ways to handle state in React. Since we're using React functional components, we'll use the now-famous React Hooks. Hooks were added to React in 2018 (which makes it a relatively recent feature as of 2021). It's a promising feature that makes state handling code more readable and easier to maintain. There are tons of materials online to go in-depth about it, and the official React doc is a good starting point.

To start handling state with React Hooks, we need to understand what our state is. In our case, it'll be the characters array. And we'll use the so-called useState() Hook to add some local state to the MyApp component. The useState call returns a pair: the current state value and a function that lets you update the state. You can call this function from an event handler or somewhere else (we'll do it soon).

Inside src/MyApp.js

import React, {useState} from 'react';
import Table from './Table';

function MyApp() {
   const [characters, setCharacters] = useState([  
      {
        name: 'Charlie',
        job: 'Janitor',
        // the rest of the data
      },
    ]);
}

Our data is officially contained in the state owned by the MyApp component (rather than contained as a constant in a function). Since we want to be able to remove a character from the table, we're going to create a removeOneCharacter function on the parent MyApp component. Note that it is a nested function. Since that function, removeOneCharacter, needs the 'characters' state, they need to be in the same scope.

To retrieve the state, we'll refer to the corresponding state identifier characters. To update the state, we'll use setCharacters(). We'll filter the array based on an index that we pass through, and return the new array. The filter function is a powerful Javascript built-in function worth checking if you're not familiar with.

You must use setCharacters() to modify the state instead of trying to assign a new value directly to characters. When you call setCharacters in the component, React automatically updates the child components inside it too (that is, React re-renders the child components to update them).

Inside src/MyApp.js

import React, {useState} from 'react';
import Table from './Table';

function MyApp() {
   const [characters, setCharacters] = useState([  
      {
        name: 'Charlie',
        job: 'Janitor',
        // the rest of the data
      },
    ]);

   function removeOneCharacter (index) {
      const updated = characters.filter((character, i) => {
         return i !== index
      });
      setCharacters(updated);
   }

}

filter does not mutate the original array but rather creates a new array after applying the filtering. And our filtering criterion is defined by a conditional statement. The conditional is testing an index vs. all the indices in the array, and returning all but the one that is passed through.

Also, note that we defined the removeOneCharacter function within the MyApp main function. With that, we can be in the right scope to refer to characters and setCharacters, and since this function will only be used within the MyApp component (which is a function by itself). Btw, we'll now see how that new function will be called.

Now, we have to pass that function through to the component and render a button next to each character that can invoke the function. First, we'll pass the removeOneCharacter function through as a prop to Table.

Inside src/MyApp.js (only showing the return -- the component render)

  return (
    <div className="container">
      <Table characterData={characters} removeCharacter={removeOneCharacter} />
    </div>
  );

Note the added prop is removeCharacter and its value in that scope is removeOneCharacter.

Since our Table component is passing the props down to TableBody, we're going to have to pass the new prop through as well, just like we did with the character data.

Inside src/Table.js

function Table(props) {
  return (
    <table>
      <TableHeader />
      <TableBody characterData={props.characterData} removeCharacter={props.removeCharacter} />
    </table>
  );
}

Now, here's where that index we defined in the removeOneCharacter() function comes in. In the TableBody component, we'll pass the key/index through as a parameter, so the filter function knows which item to remove. We'll create a button with an onClick property and pass the index through. If you're not very familiar with HTML, button is an HTML tag that has an attribute called onClick used to assign action when the button is clicked. The only change in the TableBody component is in the return call by adding a new column to the table that'll have a button with an action.

Inside src/Table.js (only changing inside the return of TableBody component)

<tr key={index}>
  <td>{row.name}</td>
  <td>{row.job}</td>
  <td>
    <button onClick={() => props.removeCharacter(index)}>Delete</button>
  </td>
</tr>

Great! Now we have delete buttons on a new column and we can modify our state by deleting a character. I deleted Mac in the screenshot below.

Now you should understand how state gets initialized and how it can be modified.

Oh, and if you want to add a column label to that new column we added in the table body (see the 'Remove' label in the picture above), guess where you should change it? Go ahead and do it for aesthetic purposes.

4 - Committing changes and pushing them to GitHub

It's always a good practice to breakdown your programming sessions into small commits. So, now it's a good time to commit the changes you've made up to this step. Remember to stage your files, otherwise, there's nothing to commit. Git is tracking your changes. Run git status to check what git has to tell you. Then, run git add <files> to stage the files (you can stage them at once using regular expressions).

Once they're staged, run git commit -m 'your commit msg.'

Finally, run git push to push your commit to GitHub.

5 - Creating a form to input data

Back to the project, now we have data stored in component state, and we can remove any item from our list of characters inside the component state. However, what if we wanted to be able to add new data to the state? In a real-world application, you'd more likely start with empty state and add to it, such as with a to-do list or a shopping cart.

Before anything else, let's remove all the hard-coded data from characters, as we'll be updating that through an input form now.

**Inside src/MyApp.js (empty state)

   const [characters, setCharacters] = useState([]);

Now, let's go ahead and create a Form component in a new file called Form.js. We're going to set the initial state of the Form to be an object with some empty properties.

src/Form.js

import React, {useState} from 'react';

function Form() {   
   const [person, setPerson] = useState(
      {  
         name: '',
         job: '',
      }
   );

}
export default Form;

Our goal for this form will be to update the state of Form every time a field is changed in the form, and when we submit the form, all that data will pass to the MyApp state (feeding the list of characters), which will then update the Table. Remember that when a component state changes, it triggers an update on the child components. State handling is where all the magic happens in React!

First, we'll make the function that will run every time a change is made to an input. The event will be passed through, and we'll set the state of Form to have the name and job of the inputs.

Add the following code to src/Form.js

function handleChange(event) {
  const { name, value } = event.target;
  if (name === "job")
     setPerson(
        {name: person['name'], job: value}
     );
  else
    setPerson(
        {name: value, job: person['job']}
     );   
}

The function above should be defined inside the Form function since it sets the state defined inside the Form component. They need to be in the same scope.

Also, note that there's only one event at a time (either changing the name or the job field), so the function above will be called every time one of the fields (name or job) changes its value (i.e., when the user types in something).

Let's get this working before we move on to submitting the form. In the render (return call), let's get our two properties from state, and assign them as the values that correspond to the proper form keys, so the state (person) will be our source of truth for the form fields. We'll run the handleChange() function as the onChange of the input.

Inside src/Form.js (the return call of the Form function)

return (
    <form>
      <label htmlFor="name">Name</label>
      <input
        type="text"
        name="name"
        id="name"
        value={person.name}
        onChange={handleChange} />
      <label htmlFor="job">Job</label>
      <input
        type="text"
        name="job"
        id="job"
        value={person.job}
        onChange={handleChange} />
    </form>
);

In MyApp.js, we can render the form below the table. A new import for bringing in the Form component to src/MyApp.js

import Form from './Form';

src/MyApp.js (Adding the form component after the table)

return (
  <div className="container">
    <Table characterData={characters} removeCharacter={removeOneCharacter} />
    <Form />
  </div>
);

6 - Debugging frontend code on the browser

Some popular browsers such as Chrome and Firefox offer developer tools that allow us to debug our code on the frontend. For instance, if you're on Chrome you can either right-click on a page and select 'inspect' or you can access View -> Developer -> Developer Tools.

I recommend you install these Chrome or Firefox extensions to improve your experience in debugging React code using the browser developer tool: React dev tools by FB and the same for Firefox.

If you install this tool, you should be able to open the developer tools in the browser and monitor the Form internal state being updated every time you change the input fields (any time you type something in will trigger the onChange event).

7 - Submitting form data

Before we actually start this next step, it's already a good time to commit current changes. In projects where you collaborate with other developers, make small commits and more frequent pushes a habit. You should run here the same as you did in Step 4.

Cool. The last step is to allow us to actually submit that data and update the parent state. We'll create a function called updateList() on MyApp that will update the state by taking the existing characters and adding the new person parameter, using the ES6 spread operator.

Inside src/MyApp.js (a new function inside the MyApp function)

function updateList(person) {
  setCharacters([...characters, person]);
}

Make sure you defined the function above as a nested function (that function goes inside the MyApp function). And let's make sure we pass that through as a parameter on Form. Note that the 'Form' capitalized is our React component.

<Form handleSubmit={updateList} />

Now, in Form, we'll create an inner function called submitForm() that will call the prop handleSubmit, and pass the Form state through as the person parameter we defined earlier. It will also reset the state to the initial state, to clear the form after submit.

Inside src/Form.js (a new inner function)

function submitForm() {
  props.handleSubmit(person);
  setPerson({name: '', job: ''});
}

Again, note the function above is a nested function. It should be defined inside the Form function since it uses the 'person' state that is within the Form scope.

And since we're now using handleSubmit prop (code above), we need to make it visible by adding 'props' as a parameter of the Form function.

src/Form.js (adding the props parameter)

function Form(props) { ... } //same function just showing we add a parameter 'props'

Finally, we'll add a submit button to submit the form. We're using an onClick instead of an onSubmit since we're not using the standard submit functionality (i.e., we're not sending the form to a backend component over the network yet). The click will call the submitForm we just made.

<input type="button" value="Submit" onClick={submitForm} />

Voila! The app is complete! We can add pairs of names and jobs to the table and delete them. Since the Table and TableBody were already pulling from the MyApp state, it will display properly.

To review what you did, take a moment to write down the resulting component hierarchy, mark what state each component handles, and in what direction data is moved around on each action (typing in the form, submitting form, and deleting rows).

If you followed the previous steps, all you have to do here is to commit and push your last changes. You will do exactly what you did in Step 4 (stage files, commit them, and push to GitHub).

If you reached this point, good job! You just completed your first React app with Hooks while following a basic git/github workflow. You used skills, tools, and practices that are valued in our industry.

If you want to discuss anything related to this content, please drop me a line on Twitter (@BrunoDaSilvaSE) or a comment below.

I welcome your feedback!

Building Your First React App with Hooks (Part I)

Bruno da Silva — Thu, 16 Sep 2021 18:10:20 +0000

Getting Started with React

The goal of this tutorial is to walk you through bootstrapping your first React app. Once you finish, continue it with Part II which includes state handling with Hooks along with Git/GitHub.

The only hard prerequisite is to have previous knowledge of programming in any language. Basic knowledge of HTML and JavaScript definitely helps, but if you don't have it, you will still be able to follow this tutorial. Several good HTML and JavaScript resources are available online, and you can't go wrong with these: HTML Guide and JavaScript Guide.

0 - Installing Node.js and npm

In this article, we will not use Node.js, but we'll need npm that comes with Node.js. If you have it already on your computer, skip this section. Otherwise, go to https://nodejs.org/en/download/ and install it according to your operating system. npm is a top-rated package manager that we'll use to install the starter code for this tutorial. It'll be useful on the next tutorials, too.

1 - Pulling Starter Code

For this section, you need npm (see the previous section). You can check it by running

npm -version

Fortunately, Facebook has created Create React App, an environment that comes pre-configured with everything you need to build a React app. To set up create-react-app, run the following code in your terminal, one directory up from where you want the project to live.

npx create-react-app react-tutorial1

Once the installation finishes, you'll see a folder named 'react-tutorial1'. Move to this folder and run the starter app.

cd react-tutorial1

npm start

A new window will popup at localhost:3000 with your new React app.

To see how the environment automatically compiles and updates your React code, find the line that looks like this in /src/App.js:

Edit <code>src/App.js</code> and save to reload.

And replace it with any other text. Once you save the file, you'll notice localhost:3000 compiles and refreshes with the new data.

Cool. You just ran a sample React app. Now, it's time to create our own.

2 - Creating Our First App

We'll reuse the environment we installed in the previous section, but we'll not use their application code. So, we'll go ahead and delete all the files in /src folder (and keep the folder).
Let's create our own boilerplate files without any bloat in our /src folder: index.css and index.js
In index.css, just copy-and-paste the contents of Primitive CSS into the file. If you want, you can use Bootstrap or whatever CSS framework you want, or nothing at all (just pure HTML without any style). Note: if you're lost on what CSS is, check other resources online, such as this page.

Now, in index.js, here's the code to add:

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
function MyApp() {
    return (
      <div>
        <h1>Hello, React!</h1>
      </div>
    );  
}
ReactDOM.render(<MyApp />, document.getElementById('root'));

In this index.js module, we're importing React, ReactDOM, and the style file (CSS). Then, we define the MyApp component as a function that returns what is supposed to be rendered on the screen. React functional components must return an element to be rendered on the page. The element can be a nested structure, as you see in the example.

The very last line in that file is going to make our React component (named here as 'MyApp') to be injected in the root of an HTML page that goes into the browser.

3 - More Components and Modularizing them in Separate Files

Almost everything in React consists of components, which can be functional components or class components (we're using functional components only). Although not required, it's a good practice to keep groups of co-related components in separate files. It helps to read and navigate through a larger codebase, and ultimately maintain it over time. So, we'll extract our MyApp component to a separate file. As a result, we'll have:

src/index.js

import React from 'react'
import ReactDOM from 'react-dom'
import MyApp from './MyApp'
import './index.css'

ReactDOM.render(<MyApp />, document.getElementById('root'));

src/MyApp.js

import React from 'react'
function MyApp() {
    return ( 
      <div> 
         <h1>Hello, React!</h1> 
      </div> 
    ); 
}
export default MyApp;

Note the last line in the MyApp.js file. It makes the component available to be imported into other modules (like we did in the index.js - see the import).

Now, let's create another React component. We're going to create a table on the page. Create Table.js, and fill it with the following sample data.

src/Table.js

import React from 'react'
function Table() { 
    return (
      <table>
        <thead>
          <tr>
            <th>Name</th>
            <th>Job</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Charlie</td>
            <td>Janitor</td>
          </tr>
          <tr>
            <td>Mac</td>
            <td>Bouncer</td>
          </tr>
          <tr>
            <td>Dee</td>
            <td>Aspiring actress</td>
          </tr>
          <tr>
            <td>Dennis</td>
            <td>Bartender</td>
          </tr>
        </tbody>
      </table>
    );
}
export default Table;

With that, we just created a new component called Table. Essentially, this is a custom-made HTML table that we coded as a React component. Note that we capitalize React component names (as we did with MyApp component) to differentiate them from regular HTML elements.

Back in MyApp.js, we can load in the Table, first by importing it in, then by loading it into the return block of MyApp, where before we had "Hello, React!". I also added the style class of the outer container (note the className property of the div element pointing to a style class from the CSS file).

src/MyApp.js

import React from 'react'
import Table from './Table'
function MyApp() { 
  return (
      <div className="container">
        <Table />
      </div>
  );  
}
export default MyApp;

If you check back on your live environment, you'll see the Table loaded in. If you don't see any results, make sure you haven't killed the "npm start" process. Also, if for some reason you closed your browser, you can reload the app by accessing http://localhost:3000 again.

4 - Components and Sub-components

Besides nesting HTML elements we can also nest React components. Let's take our Table and make two simple components for it - a table header and a table body.

src/Table.js

function TableHeader() {
  return (
    <thead>
      <tr>
        <th>Name</th>
        <th>Job</th>
      </tr>
    </thead>
  );
}

src/Table.js

function TableBody() {
  return (
    <tbody>
      <tr>
        <td>Charlie</td>
        <td>Janitor</td>
      </tr>
      <tr>
        <td>Mac</td>
        <td>Bouncer</td>
      </tr>
      <tr>
        <td>Dee</td>
        <td>Aspiring actress</td>
      </tr>
      <tr>
        <td>Dennis</td>
        <td>Bartender</td>
      </tr>
    </tbody>
  );
}

Now our Table module will look like this. Note that the TableHeader and TableBody components are all in the same file, and being used by the Table functional component.

src/Table.js

function TableHeader() { ... }
function TableBody() { ... }
function Table() { 
    return (
      <table>
        <TableHeader />
        <TableBody />
      </table>
    );
 }
export default Table;

Everything should appear as it did before. As you can see, components can be nested in other components. We kept the table components (Table, TableHeader, and TableBody) in the same module since they're closely related to each other so there's no need to define them in separate modules.

5 - Props

Right now, we have a cool Table component, but the data is being hard-coded. One of the big deals about React is how it handles data, and it does so with properties, referred to as props, and with state. Now, we'll focus on handling data with props. In Part II we'll deal with state handling.

First, let's remove all the data from our TableBody component.

src/Table.js

function TableBody() {
  return <tbody />
}

Then let's move all that data to an array of objects. We'll create this array inside our top component in the hierarchy MyApp and then pass the data down to the children.

src/MyApp.js

const characters = [
      {
        name: 'Charlie',
        job: 'Janitor',
      },
      {
        name: 'Mac',
        job: 'Bouncer',
      },
      {
        name: 'Dee',
        job: 'Aspring actress',
      },
      {
        name: 'Dennis',
        job: 'Bartender',
      },
];

function MyApp() {
    return (
      <div className="container">
        <Table />
      </div>
    );  
}

Now, we're going to pass the data through to the child component (Table) with properties. We can call the property whatever we want, as long as it's not a reserved keyword, so I'll go with characterData. The data I'm passing through is the characters variable, and I'll put curly braces around it as it's a JavaScript expression within an HTML element.

src/MyApp.js

return (
  <div className="container">
    <Table characterData={characters} />
  </div>
)

Now that data is being passed through to Table, we have to work on accessing it from the other side.

src/Table.js

function TableHeader() { ... }
function TableBody() { ... }

function Table(props) {
   return(
      <table>
        <TableHeader/>
        <TableBody characterData={props.characterData} />
      </table>
   );
}
export default Table;

In Table, we can access all props. We're only passing one prop through (characterData), so we'll use props.characterData to retrieve that data.

Since our Table component actually consists of two smaller simple components, I'm going to pass it through to the TableBody, once again through props.

Right now, TableBody takes no parameters and returns a single tag. We're going to pass the props through as a parameter, and map through the array to return a table row for each object in the array. This map will be contained in the rows variable, which we'll return as an expression.

src/Table.js

function TableHeader() { ... }

function TableBody (props) {
  const rows = props.characterData.map((row, index) => {
    return (
      <tr key={index}>
        <td>{row.name}</td>
        <td>{row.job}</td>
      </tr>
    );
  });
  return (
      <tbody>
         {rows}
      </tbody>
   );
}

function Table(props) {
   return(
      <table>
        <TableHeader/>
        <TableBody characterData={props.characterData} />
      </table>
   );
}
export default Table;

If you view the resulting page of the app, all the data is loading in now.

You'll notice we've added a key index to each table row. You should always use keys when making lists in React, as they help identify each list item. We'll also see how this is necessary in another tutorial when we want to manipulate list items.

Props are an effective way to pass existing data to a React component, however, the component cannot change the props - they're read-only. In the next React article (Part II), we'll learn how to use state to have further control over handling data in React.

This article was adapted from https://www.taniarascia.com/getting-started-with-react

If you want to discuss anything related to this content, please drop me a line on Twitter (@BrunoDaSilvaSE) or a comment below.

I welcome your feedback!

Implementing your first REST API with Express and Node.js

Bruno da Silva — Mon, 13 Sep 2021 20:36:19 +0000

This article walks you through building your first REST API as a backend component you can deploy on the web. The target audience is beginners in either REST APIs or Express/Node.js frameworks. In the end, you'll have a chance to evolve the code by yourself. Use it to self-assess if you need further study on this matter or seek help.

This article was initially created as a lab assignment in an intro to software engineering course I've taught at Cal Poly. Follow me, and soon you'll see a series of other articles associated with this project, such as a React frontend app to consume this API, database connection, testing, and continuous integration. Stay tuned.

We'll build our backend in JavaScript (Node.js) with a framework called Express.js. Express is a lightweight web development framework that is straightforward to build REST APIs for web applications and beyond.

0 - Installing Express.js

This article assumes you already have Node.js installed on your computer. If you don't, please go to nodejs.org, download and install it. To install Express, create a folder for your backend project and move to that folder. For instance, on your terminal, run:

mkdir expressjs-backend
cd expressjs-backend

Now, we need to run the npm init command to make this folder a Node.js project folder. A Node.js project folder is characterized by a package.json file (among other elements we'll see).

npm init

This command prompts you for several items, such as the name and version of your application. For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: entry point. Enter backend.js, or whatever you want the name of the main file to be. If you want it to be index.js, hit RETURN to accept the suggested default file name. At any time, you can edit your package.json file and modify that info.

To conclude this step, we'll use npm to install express:

npm install express

At this point, your project folder has the package.json file (and a package-lock.json file) with the express dependency you just installed and the /node_modules folder that will aggregate all dependencies needed to build and run your project.

1 - Creating a Hello World

First, let's create a hello world in Express to ensure we have all the environment set up to continue.

Continuing on the same folder from the previous step, create the main file for your backend service (your REST API). I named my main file backend.js (see the last step). So I'll create this file and open it on my code editor. If your main file is index.js, proceed with creating this file accordingly.
A minimal Express application looks something like this:

const express = require('express');
const app = express();
const port = 5000;

app.use(express.json());

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`);
});

So, what does that code do?

First, we imported the Express module. Express will work as an HTPP middleware dispatching HTTP calls to the routes we define in the file and also sending back responses that we'll program.
Next, we create an instance of Express and define a constant to represent the port number we'll use to listen to incoming HTTP requests.
On the fourth line, we set up our express app to process incoming data in JSON format. With that, Express (as a middleware) will allow us to access JSON data seamlessly in memory.
Then, we set up our first API endpoint with the app.get function. This sets the endpoint to accept http GET requests. And the app.get has two arguments. First, '/' is the URL pattern that will map to this endpoint. Second, we have the callback function that'll be called when our server receives an incoming GET request matching the '/' URL pattern. This anonymous function receives two objects, one representing the request (req) and the other representing the response (res). Inside the function, we can use those objects to process the request and send a response to the client that called the REST API. For now, we just use the response object to send a msg back.
Finally, we make our backend server listen to incoming http requests on the defined port number.

To run the application, type the following command on the terminal:

node backend.js [or whatever filename you used]

And you should see the following output on the terminal:

Example app listening at http://localhost:5000

Now head over to http://localhost:5000/, and you should see your hello world greeting since that represented a request to the '/' (root) route of your backend.

If you get errors at this point, they will most likely be: (i) syntax errors on the JavaScript file; (ii) fail to install the express package or node.js environment.

Before moving to the next step, I recommend that you initialize this folder with git (git init command in the folder) to start version-controlling it with git and later push changes to GitHub. After running git init, create a .gitignore file to ignore your /node_modules folder and prevent it from being uploaded to GitHub when you push your changes. Just add the '/node_modules' to an empty .gitignore file and save it. In rare situations, you would want your /node_modules folder uploaded. In most cases, having your /node_modules on the remote repo is a mistake.

You can also create a GitHub repo for this project. Stage and commit your changes. And if you have a GitHub repo, push your changes to remote.

2 - Beyond the "/" route

Our "/" route mapped to a simple "Hello World" string response. Still, it's exposed as a REST API. Essentially, any application written in any language can make a GET http request to your API endpoint and obtain the http response with the Hello World message. Although this might not sound useful, the infrastructure is already set up, which is very helpful.
Let's now make a new route to allow clients to retrieve a list of "users".

Here's the data structure to add to your JavaScript file:

const users = { 
   users_list :
   [
      { 
         id : 'xyz789',
         name : 'Charlie',
         job: 'Janitor',
      },
      {
         id : 'abc123', 
         name: 'Mac',
         job: 'Bouncer',
      },
      {
         id : 'ppp222', 
         name: 'Mac',
         job: 'Professor',
      }, 
      {
         id: 'yat999', 
         name: 'Dee',
         job: 'Aspring actress',
      },
      {
         id: 'zap555', 
         name: 'Dennis',
         job: 'Bartender',
      }
   ]
}

This is in the form of a JSON object.

Now, we'll define the '/users' GET route which will return the entire list of users. Here's the code to add to your JavaScript file.

app.get('/users', (req, res) => {
    res.send(users);
});

Again, head over to http://localhost:5000/, and you should see the response content in json format.

Git-commit current changes and continue. Push changes to GitHub if you've already set up a remote repo there.

3 - Using nodemon and avoid having to restart the server manually

At this point, you may have noticed that you need to manually kill the server and restart it again every time you change the code. This is very inconvenient while you're programming and making changes to your code constantly. Then, we'll install a package called 'nodemon' and use it to run our app backend to overcome this scenario. On the root of your project folder, run:

npm install --save-dev nodemon

We're using the save-dev argument because this is a project dependency only needed in the development environment. This is not a necessary dependency at runtime in a production-like environment. You can look at your package.json file and note a separate section for dev dependencies.

Now, instead of running your backend app with 'node', we can run it with nodemon. Nodemon will execute node, but beyond that, it'll restart the server every time you save changes on the code.

nodemon backend.js

Make any changes to your code and note nodemon automatically restarting the server.

Another good practice is to edit the package.json file and add two new script targets for running the app. In your package.json file, the "scripts" section will look like this:

"scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "nodemon backend.js", "start": "node backend.js" },

Now, if you type in your console "npm run dev" you'll run the backend app with nodemon. And if you type "npm start" you'll use node. Typically, you use "npm run dev" while coding your backend, and "npm start" will be used when you want to run your app in the production environment or as part of a CI/CD pipeline (out of this article scope). These changes won't make much difference for now, but they will make much more sense when we start working with continuous integration & deployment. For now, this step helps you explore a bit more the package.json file and become more familiar with it.

4 - Getting users by name

Suppose that, besides fetching all users, we want to retrieve users with a certain name. To do that, we do not need to create a new route. We can use http query strings to pass a name as an argument through the API and access it in our '/users' GET endpoint. If our query argument is name, then we can access it calling req.query.['name'] or req.query.name
In the browser (or any other web client), the URL will be …/users?name=Mac, where Mac is an example of a name I'm looking for.

Now we know how to pass an http query argument as part of a GET method, with a bit of logic we can find specific users with a given name to return in our get users endpoint. A possible solution for that is this one:

app.get('/users', (req, res) => {
    const name = req.query.name;
    if (name != undefined){
        let result = findUserByName(name);
        result = {users_list: result};
        res.send(result);
    }
    else{
        res.send(users);
    }
});

const findUserByName = (name) => { 
    return users['users_list'].filter( (user) => user['name'] === name); 
}

And Step 4 is done! On your browser, access http://localhost:5000/users?name=Mac, and you should see the response containing the two users with the name 'Mac'. Take the chance to play around with different values for the query argument name.

[Git-commit current changes and continue]

5 - Getting users by ID

The way you define your API routes is relevant. A good practice is to avoid action names (e.g., get-users) when dealing with basic operations (create, retrieve, update, delete) over an entity-set of your application (in our case 'users'). In our example, everything should be over the route '/users' or variations of it '/users/', which we'll explore in this current step.

This other article gives you more background on REST API design, including how you should name the API operations by properly leveraging the http methods (GET, POST, PUT, DELETE, PATCH). It's out of the scope of this article to cover everything about web API design.

In this step, we'll address the '/users/:id' GET endpoint which should be used when we want to retrieve a specific user by the given id. Here, we're assuming the id field uniquely identifies a user. Express allows you to use the ':' symbol to mark a variable that is part of the URL (don't confuse it with query arguments explored in the previous step). This variable will be then passed to the endpoint function you create to handle the requests coming from that route. Since our route is '/users/:id', we'll create a function accordingly.

With a bit of logic, we can find the right user with a given id. Otherwise, we respond with a 404 resource not found msg.

app.get('/users/:id', (req, res) => {
    const id = req.params['id']; //or req.params.id
    let result = findUserById(id);
    if (result === undefined || result.length == 0)
        res.status(404).send('Resource not found.');
    else {
        result = {users_list: result};
        res.send(result);
    }
});

function findUserById(id) {
    return users['users_list'].find( (user) => user['id'] === id); // or line below
    //return users['users_list'].filter( (user) => user['id'] === id);
}

Note that we can use the JavaScript Array find() function for this specific intent instead of filter(). Find returns the first occurrence that matches the condition. Since we're assuming id is a unique identifier, the find() function is a possible solution, too.

Also, note the syntax to return a specific http status code (we chose 404) along with a string msg.

On your browser, access http://localhost:5000/users/zap555, and you should see only Dennis, the bartender.

[Git-commit current changes and continue]

6 - Using the POST method

With the previous endpoints, we've been reading from the backend. Now, consider we need to add a new user to the list of users. That's our first 'write' operation.

Note: we're working with data in memory, so our add operation will not be persistent. However, the API design is the same if we would implement data persistence with a database.

Again, as I said in the previous step, the route is the same: '/users'. Don't make a '/add-user' route (although that would work, it's generally a bad design). Instead, we'll reuse the same URL pattern (/users) but now handling a different action since it'll be a POST endpoint. If the http request comes as a GET request, it will do what we already did in the previous step. If the http request comes as a POST request, we'll get the json data that comes in and add it to the list.

Note: intentionally, we're not doing data validation for the sake of simplicity. For beginners, there's already a lot to bite in this work. If you feel it's still too basic for you, take data validation as a stretch goal, think about what data validation you can implement on this endpoint, pick the right http code for responding in case of invalid data, and go with it.

Express.js allows us to implement endpoints for any HTTP method (GET, POST, PATCH, PUT, DELETE, etc.). We've used GET, now we'll use POST. For now, we won't handle different HTTP codes and unsuccessful addition. Let's just assume the data is in the right format and will always be inserted. Note in the code below how we send an empty response with a given HTTP code. 200 is the default response code, but it was explicitly defined in the code below to show you how we can pass any HTTP code we want.

app.post('/users', (req, res) => {
    const userToAdd = req.body;
    addUser(userToAdd);
    res.status(200).end();
});

function addUser(user){
    users['users_list'].push(user);
}

Note how we can simply access the incoming data in the request body.

To test this step, we have to make a POST call that can't be done through the browser without an additional tool (since we need to attach a json object to be added once it gets through the API - our new user). There are several options to test our POST endpoint. One option is to install a browser add-on such as Boomerang for Chrome or Rested for Firefox, and by using their user interface you can make API calls attaching json objects manually. For instance, use this new json object to be added to the backend users list:

{
  "id": "qwe123",
  "job": "Zookeeper",
  "name": "Cindy"
}

Note the double-quotes. Even though JavaScript accepts single quotes besides double quotes (or no quotes at all for the keys in the key-value pairs), the outside world does not know you're implementing your backend in JavaScript. Besides that, we have to follow the JSON standard, which is "double quotes." It will throw a 400 bad request if you pass the json object in single quotes.

Besides using browser add-ons, another option is to install a command line tool called curl. With curl, you can make all sorts of API calls in the console text interface. Finally, you can also use more robust and complete API dev tools such as Postman.

Once you make the POST call, to finally add a new user to the list, you can make a fetch call and see your recent user added to the list.

Don't forget to git-commit current changes. If you haven't pushed to a remote server, it's also a good time to do it.
Further documentation and tutorials around Express, go to https://expressjs.com/.

7 - Now evolve the code by yourself

With what we've produced so far, you should be able to evolve the code by yourself. Here I have two tasks for you:

First, implement a hard delete operation to remove a particular user by id from the list. Hint: look at another http method called DELETE. And remember: always try to reuse existing URL patterns. Don't implement a route named '/delete-user'. Look at the resource you want to access and perform the delete action (you may have an URL pattern for it already).

Second, implement an additional action to get all users that match a given name and a given job. Hint: look at what we did in step 4 and extend it.

Don't forget to commit and push your code.

Have fun with Express and Node.js!

Notes: There are many other ways to implement what we've done in this article. Some of the choices made here have educational purposes in mind, while others are entirely arbitrary and could be replaced or avoided. If you want to discuss anything related to this content, please let me know by reaching out to me on Twitter (@BrunoDaSilvaSE) or dropping a comment below.

I welcome your feedback!