DEV Community: Precious Abubakar

Future-Proofing Your Software: A Beginner's Guide to Compatibility

Precious Abubakar — Sat, 20 Jul 2024 03:15:21 +0000

Have you ever redecorated a room? You might swap out the furniture or repaint the walls. Similarly, software is constantly evolving. Updates are essential to keep your programs running smoothly and securely. They handle bug fixes, patch security vulnerabilities, and introduce new features. However, just like a brand-new rug might not match your existing curtains, software updates can sometimes clash with older versions of the code or data formats. Hence, understanding backward and forward compatibility becomes essential.

What is Compatibility?

In large-scale applications, code changes often cannot happen at once. With server-side applications, you may want to perform a staged rollout (i.e., gradually deploying the new version to a few users before making it available to everyone), reducing the risk of downtime. With client-side applications, you're at the mercy of the user, who may not install the update for some time. As a result, old and new versions of the code may exist in the system at the same time. For the system to continue running smoothly, you need to maintain compatibility in both directions:

Backward compatibility
Forward compatibility

Forward Compatibility

When a program attempts to be as compatible as possible with future versions of itself, this is known as forward compatibility. This largely involves the old code ignoring additions by the new code; skipping formats it does not understand, instead of throwing an exception. In the context of dataflow, this means that older code can read data written by newer code.

Backward Compatibility

A program is considered backward compatible if its dependents continue to work the same way, without modification, on its older versions. In the context of dataflow, this means that newer code can read data written by older code.

For example, if you have a database and you add a new field to the schema and make it required, when the new code tries to read data written by the old code, the operation will fail because the old code has no knowledge of the required field and thus there is no value for it. This is a common mistake. A simple practice for maintaining backward compatibility in this scenario is to make all fields added after the initial deployment optional or give them a default value. For the same reason, you should not remove a required field.

Backward compatibility is usually easier to achieve because- as the author of the new code, you know how the old code works. You may keep the old code to handle its specific use-case/data format.

Why Should You Care About Compatibility?

Reduced Downtime: In case of issues with a new version, maintaining compatibility allows for a quick rollback to a stable previous version, minimizing downtime.
Improved User Experience: Backward compatibility enables older and newer versions to coexist. It reduces the pressure to force immediate updates on all users, avoiding disruptions.
Seamless Updates: New features and bug fixes can be introduced without worrying about breaking functionality for users on older versions (up to a certain point).
Evolvable Codebase: Compatibility practices such as using modules and interfaces, and loose coupling of components encourage cleaner and maintainable code that can adapt to future changes.

Challenges to Consider

Balancing New Features and Old Code: Maintaining compatibility can make it harder to introduce radical changes or completely revamp the codebase in future updates.
Increased Testing: Ensuring compatibility across multiple versions adds complexity to the testing process.
Technical Debt: Over time, prioritizing backward compatibility can lead to technical debt, where older code becomes cumbersome to maintain alongside newer versions.

Strategies for Maintaining Compatibility

Versioning

Setting up a versioning system to track the changes made with each update will help everyone understand how the software works over time.

The Semantic Versioning Specification (SemVer) is a popular versioning scheme that uses a Major.Minor.Patch (X.Y.Z) format, where you increment Z if only backward compatible bug fixes are introduced, increment Y if any new backward compatible functionality is added, and increment X for any breaking changes (i.e. backward incompatible functionality). Learn more about SemVer at www.semver.org.

Clear Deprecation Policy

Communicate a plan for phasing out older features or data formats well in advance, giving users time to adapt.

Modular Design

Break down code into smaller, independent modules so that changes in one section will have minimal impact on others. Modules are chunks of code that have specific functions. They can be reused in different parts of the program. The code snippets below are examples of a basic calculator program written in a monolithic approach vs modular approach.

function calculate(operation, num1, num2) {
  if (operation === 'add') {
    return num1 + num2;
  } else if (operation === 'subtract') {
    return num1 - num2;
  } else if (operation === 'multiply') {
    return num1 * num2;
  } else if (operation === 'divide') {
    return num1 / num2;
  } 
  return 'Invalid operation';
}

i. Monolithic design: As you can see, all the logic is in one function. This works but can become difficult to maintain if the application grows.

// operations.js
function add(x, y) { return x + y; }
function subtract(x, y) { return x - y; }
function multiply(x, y) { return x * y; }
function divide(x, y) { return x / y; }

module.exports = {add, subtract, multiply, divide}

// calculator.js
import { add, subtract, multiply, divide } from './operations.js';

function calculate(operation, num1, num2) {
  let result;
  switch (operation) {
    case 'add':
      result = add(num1, num2);
      break;
    case 'subtract':
      result = subtract(num1, num2);
      break;
    case 'multiply':
      result = multiply(num1, num2);
      break;
    case 'divide':
      result = divide(num1, num2);
      break;
    default:
      return 'Invalid operation';
  }
  return result;
}

ii. Modular Design: Here, the operations have been separated into a different module, making the code more organized and reusable.

Loose Coupling

To accommodate different versions and functionalities, code components should be loosely coupled. While modular design is about code structure, coupling is about the interaction between the components. The less they know about each other, the more loosely coupled they are. See an example of loosely vs tightly coupled TypeScript code in the snippet below.

class CartService {
    constructor(private cart: ICart) {}
    addItem(item: string) {
        this.cart.addItem(item);
    }
    removeItem(item: string) {
        this.cart.removeItem(item);
    }
}

interface ICart {
    addItem(item: string): void;
    removeItem(item: string): void;
}

class CartImpl implements ICart {
    addItem(item: string) {
        console.log(item, ' added')
    }
    removeItem(item: string) {
        console.log(item, ' removed')
    }
}

const cartService = new CartService(new CartImpl());
cartService.addItem('item1'); // result: 'item1 added'
cartService.removeItem('item1'); // result: 'item1 removed'

i. Loosely coupled: The CartService does not care how the item is added, only that it can be added. It relies on the interface ICart rather than specific implementations. This allows for flexibility as you can switch implementations (e.g., applying a discount) without modifying the CartService code.

class CartService {
  private cart: any[] = [];

  addItem(item: string) {
    this.cart.push(item);
    console.log(this.cart)
  }

  removeItem(item: string) {
    const index = this.cart.indexOf(item);
    if (index !== -1) {
      this.cart.splice(index, 1);
    }
    console.log(this.cart)
  }
}

const cartService = new CartService();
cartService.addItem('item1'); // result: ['item1']
cartService.removeItem('item1'); // result: []

ii. Tightly coupled: This approach can lead to maintainability issues and reduced flexibility. However, tight coupling is not always a bad thing, so one must always consider the trade-offs of both architectures. Learn more about coupling here- It’s All About (Loose) Coupling — PragmaticCoding.

Automated Testing

Automated testing frameworks ensure compatibility across different versions during development.

Conclusion

While compatibility should not be overlooked, striking the right balance is key. Maintaining support for older versions can consume valuable resources. For example, continuing to support Node.js v4 might be impractical, given the availability of several newer, more efficient versions. Always weigh the benefits of supporting older versions against the cost and potential risks.

By carefully considering these factors and implementing effective compatibility strategies, you can create software that adapts to change while minimizing user disruptions. For a deeper dive into software evolution, compatibility and other system design concepts, check out the resources below.

References

Understanding Software Licenses: A Developer's Guide

Precious Abubakar — Sat, 10 Jun 2023 23:38:06 +0000

Software licenses are legally binding documents that provide guidelines for the use, modification, and distribution of software. Understanding software licenses is essential for a developer to make informed decisions when it comes to using and contributing to open source projects or creating proprietary software.

This article provides an overview of software licenses and the different types of licenses that a developer may encounter.

Types of Software Licenses

Public Domain License
A public domain license (CC0) waives all rights to the software. If your project is in the public domain, that means it is not protected by any copyright laws and can be freely used, modified, and distributed.
Proprietary License
Proprietary licenses restrict the distribution, modification, and use of software. The software owner usually maintains control over the source code, features, and usage of the software.
Open Source/Permissive License
Open source licenses allow software to be used, modified, and shared without restrictions. They align with the specifications of the Open Source Definition. e.g. MIT license.
Copyleft License
Copyleft licenses are designed to promote free software. “Free” in this context refers to the freedom to share and modify works. The most common one is the GNU General Public License (GPL). The GPL is similar to open source licenses, but it requires that any modifications or derived works be released under the same GPL license. This ensures that the software and its derivatives remain open source and accessible to the community.

Benefits of Software Licensing

A license grants permission so that you don’t have to do it for each individual user.
Licenses protect your intellectual property. They control how your software/source code can be used and prevent piracy.

Open Source Licenses

Open Source Initiative (OSI) has an exhaustive list of open source licenses. The most commonly used ones are highlighted below.

The MIT License

The MIT License grants permission to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software under certain conditions.

The first condition is that the license text must be included in all copies or substantial portions of the software. This ensures that anyone using the software knows that it is licensed under the MIT License and is aware of the license terms.

The second condition is a disclaimer of liability, which means that the authors or copyright holders cannot be held responsible for any problems that may arise.

In summary, the MIT License is a permissive software license that allows users to do almost anything they want with the software, as long as they include the license text and do not hold the authors or copyright holders liable for any problems that may arise.

GNU General Public License (GPL)

The GNU General Public Licenses grant permission to use, modify or use pieces of the software in new programs, and distribute copies of the software. It requires that the source code is made available to users, and allows for commercial use and distribution of the software.

Unlike MIT, the GNU General Public License is a copyleft license, which means that distributed works based on the software are required to use the same license as the original. As a result of this, software licensed under the GPL cannot be used in paid or proprietary software. However, the Lesser General Public License exists for this purpose.

GNU Lesser General Public License (LGPL)

The GNU Lesser General Public License is similar to the GPL, but without certain restrictions. It allows users to modify and distribute the software without adopting a GNU License, allowing it to be used in proprietary software.

Apache License (Apache-2.0)

The Apache License is a permissive license that grants individuals and organizations permission to freely use, modify, and distribute software.

An interesting feature of the Apache License is its patent clause. This clause grants users the right to use any patents that the contributors to the software may hold. This can be helpful if you are using the software for commercial purposes, as it can help protect you from patent infringement claims.

Like most open source licenses, The Apache License also contains a disclaimer of warranties and limitations of liability. This means that the software is provided “as is” and that the original creators of the software cannot be held responsible for any damages that may result from using the software

If you create a derivative work based on software licensed under the Apache License, you must include a copy of the Apache License in the new work and retain any copyright, patent, and trademark notices that were included in the original software. You must also clearly indicate any modifications that you made to the original work, and include attribution notices to give credit to the original creators of the software.

Overall, the Apache License is a flexible and permissive license that allows for broad use of open-source software, while also providing some protections for both users and contributors.

BSD License

The BSD license allows users to modify, distribute, and use the licensed software without any restrictions on the licenses of derivative works.

The BSD License comes in two forms: the two-clause BSD license and the three-clause BSD license. The two-clause BSD license only contains a copyright notice and a disclaimer of warranties, while the three-clause BSD license adds an additional clause that requires users to include attribution notices in derivative works.

Similar to other open-source licenses, such as the Apache License, the BSD License contains a disclaimer of warranties and limitations of liability.

Overall, the BSD License is a popular choice for open-source projects that value flexibility and minimal restrictions on the use and distribution of their software. However, it may not be the best choice for projects that require stronger protections for their intellectual property.

Mozilla Public License (MPL)

The Mozilla Public License (MPL) is a permissive open-source license that allows users to modify, distribute and use the licensed software without any restrictions on the licenses of derivative works. It is also a copyleft license, as it requires that any derivative works include a copy of the MPL and retain any copyright, patent, and trademark notices.

The MPL also contains a patent license clause that provides users with the right to use any patents that a contributor to the software may own. The license has a disclaimer of warranties and limitations of liability, similar to other open-source licenses.

One drawback of the MPL is that it may be less compatible with other open-source licenses than some of the more permissive licenses, such as the MIT or Apache Licenses. This can limit the potential for collaboration between projects that use different licenses. However, the MPL is still a widely used open-source license and is particularly popular for software projects with a strong focus on community development and collaboration.

Proprietary Licenses

Some common types of proprietary software licenses are highlighted below.

End User License Agreement (EULA)

An End User License Agreement (EULA) is a legally binding contract between the user and the software owner, which defines the terms and conditions under which the software can be used. Lots of companies make use of EULAs. For example, Microsoft uses an EULA for Windows.

The EULA restricts the user from modifying the software, distributing it without permission, or using it in certain ways.

An EULA must be clear and concise. It must contain the following information:

Copyright notice
Infringement acknowledgment
Licensor information
Software information
Relevant laws
Warranty Disclaimer
Restrictions for use
Site licenses
Start date
Termination of licensing
License granting

For a sample, try this free EULA generator.

Perpetual License

A perpetual license is an old model of licensing that permits users to use the software indefinitely, after a one-time payment. The license holder has access to that specific version of the software indefinitely. This model is being phased out in favor of subscription-based license models because it does not account for updates and patches, just a one-time revenue hit, which makes it problematic for software owners and end users. It was popular in the early days when you purchased a program by buying a disk with a built-in license.

AutoCAD (a design software) used to have a perpetual license, but has moved to a subscription license.

Subscription License

Software has evolved from being perceived as products to Software as a Service (SaaS), and the subscription license model has taken over. It involves paying a regular fee (monthly, annually, or otherwise) to use software, as opposed to a one-time purchase.

Subscription licenses offer benefits such as updates and flexibility. With a subscription license, you can offer different tiers of service, and users can choose what meets their needs. Your users can also upgrade or downgrade their subscription based on their changing requirements, reflecting the adaptability needed in today’s dynamic world.

Subscription-based licenses eliminate the need for a significant upfront investment as opposed to perpetual licenses. Budgeting becomes easier with regular smaller payments compared to a large one-time payment. Maintenance, upgrades, and renewals are typically included in the subscription cost, unlike perpetual licenses which may require additional expenses as warranties expire. A lot of modern software uses subscription licenses, e.g. Adobe Creative Suite.

Floating License

A science club requests to use your library for research, and you approve their request on one condition- only one person can be granted access at any given time. Since all 5 members do not need to use the library at the same time, they have gladly accepted your offer. This is essentially how a floating license works.

A floating license grants a group of users shared access to your software. This means that the software can be installed on a network of computers, allowing access to multiple users. The downside for users is that if the floating license is for 2 users and 2 people are currently using the software, a third user would have to wait. Adobe Creative Cloud offers floating licenses for schools.

Choosing a License

Choosing the right license for your project is essential. Here are some factors to consider when navigating this process.

Project Goals
Examine the goals of your project. Think about how you want it to be If you want to generate revenue from the project and have control over its usage, proprietary licenses might be the way to go. Open source licenses are ideal for fostering community involvement and collaboration.
Community and Support
Consider the existing community and support surrounding various licenses. Open source licenses often come with communities offering assistance, comprehensive documentation, and opportunities for collaborative contributions. This support can be invaluable, providing guidance and fostering growth.
Openness
When considering a license, contemplate the level of freedom you want to grant your users. Open source licenses encourage collaboration and the sharing of knowledge, while proprietary licenses grant you greater control over your software. Note that Open Source software does not automatically mean free software (”free” in this context is referring to price).
Compatibility
Think about any obligations you have, such as licensing requirements from third-party libraries or components governed by specific licenses. Ensure compatibility between licenses to avoid conflicts or legal issues. For example, if you’re using a third-party library with a GNU GPL, your project cannot have a proprietary license.
Legal Requirements
While not the most exciting aspect, legal requirements are crucial. Take the time to acquaint yourself with the legal implications and obligations associated with different licenses. Complying with license terms helps avoid legal pitfalls and ensures a smooth development process.

Conclusion

In conclusion, understanding software licenses is vital for developers. It allows you to make informed decisions about how your software can be used, modified, and distributed. It is essential to consider factors like project goals, community support, openness, compatibility, and legal requirements when choosing a license for your project. By navigating the licensing landscape effectively, you can make the best choice for your project.

Resources

How to Overcome the Challenges of Open Source Contribution

Precious Abubakar — Wed, 12 Apr 2023 08:33:05 +0000

According to Open Source Contributor Index, 2443 people in the Microsoft community made at least one commit in January. Out of 2443 people, only 795 made 10+ commits. This suggests a gap between joining an open source project and contributing actively.

This article highlights some common challenges that open source contributors face and discuss how to tackle them.

What is Open Source Software?

Open source software (OSS) refers to software whose source code is accessible to everyone. This means that you can inspect it, alter it and enhance it from anywhere in the world. Some popular examples of open source software are VLC Media Player, Kubernetes, and Linux.

You can contribute to open source through code or no-code skills such as community management, UI/UX design, project management, graphic design, writing, discussions, and advocacy.

Benefits of Contributing to Open Source Software

Here are some reasons why you should consider contributing to open source software:

Career Growth: Contributing to OSS is a great way to gain work experience and build your portfolio. It gives you an opportunity to learn on the job, and at your own pace. You get to understand the technology on a deeper level, and you can identify problems and fix them.

You can improve your technical (or non-technical) skills by interacting and collaborating with more experienced people in your field. You can also learn valuable soft skills, like how to collaborate and work asynchronously.
Networking: It provides opportunities for you to connect with people from around the world who have similar interests. Meeting interesting people from across the world can improve the quality of your network.
Giving Back: Through OSS contributions, you can use your skills to make someone’s life easier. It’s a great way to give back to society.

Common Challenges Open Source Contributors Face

People often find it difficult to make meaningful contributions to open source even though they have an interest, owing to many reasons. Some of these reasons are highlighted below.

Finding the right project to contribute to
Lack of clear documentation
Difficulty communicating with other contributors or maintainers
Discrimination and lack of inclusion
Balancing contributions with other commitments
Projects could be overwhelming

Overcoming Challenges Faced During OSS Contributions

Here are some things you can do to make your experience smoother:

Start Small: Joining any team midway through the project lifecycle can be overwhelming. You can start by making small contributions like joining discussions, improving documentation, etc. Look out for issues with tags such as good-first-issue because they are usually easy to contribute to. This will allow you to understand the rules for contributing to that project and how to communicate with the maintainers or ask for assistance.
Seek Community-Focused Open Source Organizations/Projects: It is important for you to have support while contributing to a project, and the best way to get it is via the community. The community forum is a great communication channel and a source of information. You can join discussions, get help, and connect with people.
Look for a DEI Statement: DEI stands for diversity, equity, and inclusion. A DEI statement is a declaration of commitment to fostering a culture of diversity, equity, and inclusion in the workplace. If there is no visible DEI statement, ask about their DEI policies. If your values do not align with theirs or you do not feel supported or welcome, it is okay to leave and find one where you feel seen and accepted.
Take Advantage of the Available Resources: Community meetings and mailing lists are helpful sources of information. If you’re just joining, look out for onboarding sessions. If you’re having trouble reaching maintainers or contributors, try joining a community call. More often than not, these calls are recorded, so you can access the recordings at your convenience.
Manage Your Schedule Effectively: Typically, nobody expects a full-time commitment from you. You can work asynchronously, but communication is key. People need to know that they can depend on you to finish the task that you have taken on, so you should only accept what you can deliver within the agreed time frame. Always ask for clarification on what is expected of you.
Ask for Help: Your contribution is valuable. If there’s a problem hindering you from making a contribution, use the communication channels available to you to express yourself. They want you to add value to the project, so they are willing to support you and guide you through it. The chances that your concerns will be addressed and your questions answered are pretty high.

Best Practices for Contributing to Open Source Software

Read the contributing guidelines and adhere to them. They are usually available on the website or in a contributing.md file on the project repository.
Read the project documentation.
Make quality contributions by following standard practices in the related field.
Keep your interactions with other people respectful by using inclusive language, refraining from insults, etc.
Use the proper communication channels defined in the contributing guidelines. Do not call or email people unless they consent to it.
When in doubt, ask questions.

Conclusion

Contributing to open source software has its challenges, but it also has its benefits. A number of the challenges open source contributors face can be addressed by leveraging the support that communities provide and taking advantage of the available resources. However, the most important thing is to find a project that aligns with your interests and values. You can find open source projects here:

Resources

She Code Africa Contributhon Program

She Code Africa (SCA) promotes diversity in the open source ecosystem through Contributhon. Contributhon is a virtual open source boot camp where ladies get the opportunity to work with open source organizations on selected projects with dedicated mentorship.

This program aims to create a more diverse, inclusive, and innovative culture within the African open source ecosystem by matching African women in technology with sponsors and mentors (open source organizations) to work on projects used by millions of people all over the world.

Stay updated on information about the next cohort via SCA’s social media platforms.

Twitter: @shecodeafrica
Instagram: @shecodeafrica
LinkedIn: She Code Africa

If you’re not already a member of She Code Africa, you can begin by applying via the website: shecodeafrica.org

Building a Blog API with Node.js: Implementing the API Routes (Part 4)

Precious Abubakar — Mon, 09 Jan 2023 17:55:27 +0000

Now that we have our API design complete, the models set up, the database connection established and the authentication strategies in place, it's time to start building the actual API. In this article, we'll cover the following topics:

Implementing the routes for our API
Writing the controllers to handle requests and send responses
Testing the API with Postman

Let's get started!

Implementing the Routes

Create a file called blog.routes.js in the /routes directory and write this code:
```
const express = require("express");
const { blogController } = require("../controllers");

const blogRouter = express.Router();

blogRouter.get("/", blogController.getPublishedArticles);

blogRouter.get("/:articleId", blogController.getArticle);

module.exports = blogRouter;
```
The express.Router() function creates a new router object that can be used to define routes that will be used to handle HTTP requests to the server.

The first route defined is a GET route at the root path of the router. This route will handle HTTP GET requests to the server and will use the getPublishedArticles function from the blogController to return a list of all published articles.

The second route is a GET route that includes a parameter :articleId in the path. This route will handle HTTP GET requests to the server with a specific article ID in the path, and will use the getArticle function from the blogController to return the article with the specified ID.

Create a file called author.routes.js in the /routes directory and write this code:

const express = require("express"); 
const { authorController } = require("../controllers");
const {
    newArticleValidationMW,
    updateArticleValidationMW,
} = require("../validators");

const authorRouter = express.Router();

// create a new article 
authorRouter.post("/", newArticleValidationMW, authorController.createArticle);

// change state 
authorRouter.patch(
    "/edit/state/:articleId",
    updateArticleValidationMW,
    authorController.editState
);

// edit article
authorRouter.patch(
    "/edit/:articleId",
    updateArticleValidationMW,
    authorController.editArticle
);

// delete article 
authorRouter.delete("/delete/:articleId", authorController.deleteArticle);

// get all articles created by the author 
authorRouter.get("/", authorController.getArticlesByAuthor);

module.exports = authorRouter;

Here, we've imported the validation middleware we created in the previous article:

const {
    newArticleValidationMW,
    updateArticleValidationMW,
} = require("../validators");

When a POST or PATCH request is made, the validation middleware checks if the request body is in the correct format:

authorRouter.post("/", newArticleValidationMW, authorController.createArticle);

authorRouter.patch(
    "/edit/state/:articleId",
    updateArticleValidationMW,
    authorController.editState
);
authorRouter.patch(
    "/edit/:articleId",
    updateArticleValidationMW,
    authorController.editArticle
);

Create a file called auth.routes.js in the /routes directory for the authentication routes:
```
const express = require("express");
const passport = require("passport");
const { userValidator } = require("../validators");

const { authController } = require("../controllers");

const authRouter = express.Router();

authRouter.post(
    "/signup",
    passport.authenticate("signup", { session: false }), userValidator,
    authController.signup
);

authRouter.post("/login", async (req, res, next) =>
    passport.authenticate("login", (err, user, info) => {
        authController.login(req, res, { err, user, info });
    })(req, res, next)
);

module.exports = authRouter;
```
The signup route uses the passport.authenticate() function to authenticate the request using the signup strategy. It also specifies that session management should be disabled using the { session: false } option. If the request is successfully authenticated, it is passed to the authController.signup function for further processing.

The login route is similar, but it uses the login strategy and passes the request to the authController.login function if it is successfully authenticated.

Both routes also use the userValidator middleware to validate the request body before it is passed to the controller functions.

Create an index.js file in /routes and export the routers:

const blogRouter = require("./blog.routes"); 
const authorRouter = require("./author.routes");
const authRouter = require("./auth.routes");

module.exports = { blogRouter, authorRouter, authRouter };

Import the routers and use them in the app.js file.

// {... some code ....}
const { blogRouter, authRouter, authorRouter } = require("./src/routes");

// Middleware
// {... some code ....}

// Routes
app.use("/blog", blogRouter);
app.use("/auth", authRouter);
app.use(
    "/author/blog",
    passport.authenticate("jwt", { session: false }),
    authorRouter
);

// {... some code ....}

Remember we separated the routes into blog routes and author routes because we wanted to protect the author routes. We are using passport to protect the /author/blog routes, so that only authenticated users can have access to the resources. Unauthenticated users can only have access to the /blog routes.

Writing the Controllers

Now that we have the routes defined, we need to write the code to handle the requests and send the appropriate responses. A controller is a function that is called when a route is matched, and it is responsible for handling the request and sending the response.

Create a file called blog.controllers.js in the /controllers directory. In this file, define the functions that will be called by the blog routes:
```
const { BlogModel, UserModel } = require("../models");

// Get all published articles
exports.getPublishedArticles = async (req, res, next) => {
    try {
        const {
            author,
            title,
            tags,
            order = "asc",
            order_by = "timestamp,reading_time,read_count",
            page = 1,
            per_page = 20,
        } = req.query;

        // filter
        const findQuery = { state: "published" };

        if(author) {
          findQuery.author = author;
        }
        if (title) {
            findQuery.title = title;
        }
        if (tags) {
          const searchTags = tags.split(",");
          findQuery.tags = { $in: searchTags };
        }

        // sort
        const sortQuery = {};
        const sortAttributes = order_by.split(",");

        for (const attribute of sortAttributes) {
            if (order === "asc") {
                sortQuery[attribute] = 1;
            }
            if (order === "desc" && order_by) {
                sortQuery[attribute] = -1;
            }
        }

        // get all published articles from the database
        const articles = await BlogModel.find(findQuery)
            .populate("author", "firstname lastname email")
            .sort(sortQuery)
            .skip(page)
            .limit(per_page);

        return res.status(200).json({
            message: "Request successful",
            articles: articles,
        });
    } catch (error) {
        return next(error);
    }
};

// Get article by ID
exports.getArticle = async (req, res, next) => {
    const { articleId } = req.params;
    try {
        const article = await BlogModel.findById(articleId).populate(
            "author",
            "firstname lastname email"
        );

        article.readCount += 1; // increment read count
        await article.save();

        return res.status(200).json({
            message: "Request successful",
            article: article,
        });
    } catch (error) {
        return next(error);
    }
};
```
The getPublishedArticles function will be called when the GET /blog route is matched, and it will retrieve a list of all published articles from the database and send the response to the client. It begins by destructuring some query parameters from the req.query object. These query parameters are used to filter and sort the articles that are returned.

The sorting in this function is done using the Mongoose .sort() method, which takes an object with the field names as keys and the sort order as values. The field names and sort orders are specified in the sortQuery object, which is constructed based on the order and order_by query parameters.

The order_by query parameter is a string that can contain multiple field names, separated by commas. The sortAttributes variable is an array of these field names. For each field name in the array, the sortQuery object is updated with the field name as the key and the sort order as the value. If the order query parameter is "asc", the sort order is set to 1, and if the order query parameter is "desc", the sort order is set to -1.

The find query is constructed using the findQuery object, which is initialized with a filter to only return published articles. The findQuery object is then updated with additional filters based on the author, title, and tags query parameters, if they are present.

For example, if the author query parameter is present, the findQuery.author field is set to the value of the author query parameter. This will filter the results to only include articles whose author field is equal to the value of the author query parameter. Similarly, if the tags query parameter is present, the findQuery.tags field is set to a MongoDB operator that searches for articles with tags that match the search tags. The search tags are specified as a comma-separated string and are split into an array using the split method. The $in operator is used to search for articles with tags that are included in the array of search tags.

The findQuery object is passed as an argument to the .find() method of the BlogModel object. This method returns a Mongoose query object that can be used to find documents in the blog collection that match the specified filter. The .populate() method is then called on the query object to populate the author field with the corresponding user document, and .sort() sorts the results using the sortQuery object. .skip() and .limit() are called to paginate the results. skip() specifies the number of documents to skip in the query, and limit() specifies the number of documents to return. The page and per_page query parameters are used to determine the values passed to skip() and limit(). By default, page is set to 1 and per_page is set to 20. This means that if these query parameters are not provided, the default behavior is to retrieve the first page of results with 20 documents per page.

The getArticle function retrieves the article with the specified ID from the database and increments the article's read count before returning it to the client.

Both functions use the async keyword and include a try/catch block to handle any errors that may occur during the execution of the function. If an error occurs, the next function is called with the error as an argument to pass the error to the error handling middleware which is set up in our app.js.

Create a file called author.controllers.js in the /controllers directory and define the functions that will be called by the author routes as follows:

const { BlogModel, UserModel } = require("../models");
const { blogService } = require("../services");
const moment = require("moment");

// create a new article
exports.createArticle = async (req, res, next) => {
    try {
        const newArticle = req.body;

        // calculate reading time
        const readingTime =
            blogService.calculateReadingTime(newArticle.body);

        if (newArticle.tags) {
          newArticle.tags = newArticle.tags.split(",");
        }
        if (req.files) {
          const imageUrl = await blogService.uploadImage(req, res, next);
          newArticle.imageUrl = imageUrl;
        }

        const article = new BlogModel({
            author: req.user._id,
            timestamp: moment().toDate(),
            readingTime: readingTime,
            ...newArticle,
        });

        article.save((err, user) => {
            if (err) {
                console.log(`err: ${err}`);
                return next(err);
            }
        });

        // add article to user's articles array in the database
        const user = await UserModel.findById(req.user._id);
        user.articles.push(article._id);
        await user.save();

        return res.status(201).json({
            message: "Article created successfully",
            article: article,
        });
    } catch (error) {
        return next(error);
    }
};

// change state
exports.editState = async (req, res, next) => {
    try {
        const { articleId } = req.params;
        const { state } = req.body;

        const article = await BlogModel.findById(articleId);

        // check if user is authorised to change state
        blogService.userAuth(req, res, next, article.author._id);

        // validate request
        if (state !== "published" && state !== "draft") {
            return next({ status: 400, message: "Invalid state" });
        }

        if (article.state === state) {
            return next({ 
                status: 400, 
                message: `Article is already in ${state} state` 
            });
        }

        article.state = state;
        article.timestamp = moment().toDate();

        article.save();

        return res.status(200).json({
            message: "State successfully updated",
            article: article,
        });
    } catch (error) {
        return next(error);
    }
};

// edit article
exports.editArticle = async (req, res, next) => {
    try {
        const { articleId } = req.params;
        const { title, body, tags, description } = req.body;

        // check if user is authorised to edit article
        const article = await BlogModel.findById(articleId);
        blogService.userAuth(req, res, next, article.author._id);

        // if params are provided, update them
        if (req.files) {
          const imageUrl = await blogService.uploadImage(req, res, next);
          article.imageUrl = imageUrl;
        }
        if (title) {
            article.title = title;
        }
        if (body) {
            article.body = body;
            article.readingTime = blogService.calculateReadingTime(body);
        }
        if (tags) {
            article.tags = tags.split(",");
        }
        if (description) {
            article.description = description;
        }
        if (title || body || tags || description ) {
            article.timestamp = moment().toDate();
        }

        article.save();

        return res.status(200).json({
            message: "Article successfully edited and saved",
            article: article,
        });

    } catch (error) {
        return next(error);
    }
};

// delete article
exports.deleteArticle = async (req, res, next) => {
    try {
        const { articleId } = req.params;

        const article = await BlogModel.findById(articleId);

        // check if user is authorised to delete article
        blogService.userAuth(req, res, next, article.author._id);

        article.remove();

        return res.status(200).json({
            message: "Article successfully deleted",
        });
    } catch (error) {
        return next(error);
    }
};

// get all articles created by the user
exports.getArticlesByAuthor = async (req, res, next) => {
    try {
        const {
            state,
            order = "asc",
            order_by = "timestamp",
            page = 1,
            per_page = 20,
        } = req.query;

        const findQuery = {};
        // check if state is valid and if it is, add it to the query
        if (state) {
            if (state !== "published" && state !== "draft") {
                return next({ status: 400, message: "Invalid state" });
            } else {
                findQuery.state = state;
            }
        }

        // sort
        const sortQuery = {};

        if (order !== "asc" && order !== "desc") {
            return next({ 
                status: 400, 
                message: "Invalid parameter order" 
            });
        } else {
          sortQuery[order_by] = order;
        }

        // get user's articles
        const user = await UserModel.findById(req.user._id).populate({
            path: "articles",
            match: findQuery,
            options: {
                sort: sortQuery,
                limit: parseInt(per_page),
                skip: (page - 1) * per_page,
            },
        });

        return res.status(200).json({
            message: "Request successful",
            articles: user.articles,
        });
    } catch (error) {
        return next(error);
    }
};

The createArticle function begins by destructuring the new article data from the req.body object and calculating the reading time for the article using the calculateReadingTime function from the blogService module which we'll create next to abstract some functionalities.

Next, the function checks if the tags field is present in the newArticle data, and splits the tags string into an array using the split method. Recall that tags is defined as an array in the blog model.

Next, If the user uploads a cover image, we want to access the file, upload it to a cloud storage service, get the URL for the uploaded image and save it to our database. The express-fileupload we installed will allow us to access the req.files object.

Finally, the function creates a new BlogModel instance with the newArticle data and the current timestamp and user ID, and saves it to the database using the save method. We're using an npm module moment to handle the timestamp. You can install moment by running npm install moment.

The author field is an ObjectId referencing the User model. Here, we assign the user's ID so we can use Mongoose .populate method to retrieve the author's details when we need to.

Similarly, we want to be able to track all the articles created by the user, so next, we update the user's articles array in the database to include the ID of the new article before we return a response to the client.

In the editState function, we retrieve the article from the database and check if the user is authorized to change the state of the article. If the user is authorized, we update the article's state and timestamp in the database.

In the editArticle function, we retrieve the article from the database and check if the user is authorized to edit the article. If the user is authorized, we update the article's data in the database.

Create a file called auth.controllers.js in the /controllers directory for the authentication routes:

const jwt = require("jsonwebtoken");
const { UserModel } = require("../models");

exports.signup = async (req, res, next) => {
    const { firstname, lastname, email, password } = req.body;

    try {
        const user = new UserModel({
            firstname: firstname,
            lastname: lastname,
            email: email,
            password: password,
        });

        user.save((err, user) => {
            if (err) {
                return next(err);
            }
        });

        delete user.password;

        return res.status(201).json({
            message: "Signup successful",
            user: user,
        });
    } catch (error) {
        return next(error);
    }
};

exports.login = (req, res, { err, user, info }) => {
    if (!user) {
        return res.status(401).json({ message: "email or password is incorrect" });
    }

    req.login(user, { session: false }, async (error) => {
        if (error) return res.status(401).json({ message: error });

        const body = { _id: user._id, email: user.email };

        const token = jwt.sign({ user: body }, process.env.JWT_SECRET, {
            expiresIn: "1h",
        });

        return res.status(200).json({ 
            message: "Login successful",
            token: token 
        });
    });
};

The signup function creates a new user object with the provided first name, last name, email, and password. It then saves this user object to the database and returns a success message and the user object, minus the password field. You should never expose passwords.

The login function is called when a user attempts to log in. If the provided email and password do not match a user in the database, it returns a 401 status code and an error message. Otherwise, it creates a JWT with the user's ID and email as the payload, and signs it with a secret key (which we stored in our .env file. Since we're not using session, logging out is tricky, so we've set an expiration time of one hour for the token. The function returns a success message and the JWT.

Create a file called /index.js in the /controllers directory:

const authController = require("./auth.controller"); 
const blogController = require("./blog.controller"); 
const authorController = require("./author.controller");

module.exports = { 
    authController, 
    blogController, 
    authorController 
};

Blog Service

We abstracted some of the logic for our author.controller.js to a blogService module. Let's look into that.

Before we begin, we're using Cloudinary, a media management platform that allows you to store, optimize, and deliver images and videos. Follow the instructions on the Cloudinary website to set up your account, then install the SDK by running this command:

npm install cloudinary

Now, in /services, create a file called blog.service.js with the following functions:

const cloudinary = require('cloudinary').v2;

cloudinary.config({
  secure: true
});

exports.userAuth = (req, res, next, authorId) => {
    // if author is not the same as the logged in user, throw error
    if (req.user._id !== authorId.toString()) {
        return next({
            status: 401,
            message: "You are not authorized to access this resource",
        });
    }
};

exports.calculateReadingTime = (text) => {
    const wordsPerMin = 200;
    const wordCount = text.trim().split(/\s+/).length;
    const readingTime = Math.ceil(wordCount / wordsPerMin);

    return readingTime > 1 ? `${readingTime} mins` : `${readingTime} min`;
};

exports.uploadImage = async (req, res, next) => {
  const filePath = req.files.file.tempFilePath;

  const options = {
    use_filename: true,
    unique_filename: false,
    overwrite: true,
  };

  try {
    const uploadedImage = await cloudinary.uploader.upload(filePath, options);

    return uploadedImage.secure_url;
  } catch (error) {
    return next(error);
  }

}

The userAuth function checks if the user making the request is the same as the author of the post being accessed. If the user is not the author, it throws an error with a status code of 401 (Unauthorized).

The calculateReadingTime function takes a piece of text as an argument and calculates the estimated reading time in minutes by dividing the number of words in the text by the average number of words per minute (the average reading speed for an adult is about 200wpm according to Marc Brysbaert from Ghent University in Belgium). It then rounds up to the nearest whole number and returns a string with the reading time.

The uploadImage function uploads an image to Cloudinary and returns a secure URL. It takes req, res and next as arguments, retrieves the file path of the uploaded image from the req object and stores it in a filePath variable (this is made possible by the express-fileupload npm package we installed). It then sets up options for the upload, including the use_filename and overwrite options, which specify that the uploaded file should use its original filename and overwrite any existing file with the same name. The function then uses the cloudinary.uploader.upload method to upload the file to Cloudinary. If the upload is successful, it returns the secure URL of the uploaded file.

In /services/index.js:

const blogService = require('./blog.service.js');

module.exports = {
  blogService
}

Testing the API with Postman

With the routes and controllers in place, we can now test our API to make sure it's working as expected. You can use Postman to test all of the routes in your API to make sure they are working as expected.

To test routes that require a request body, such as POST and PATCH routes, you'll need to specify the request body in the appropriate format in the Postman request form. You'll also need to provide a bearer token in the Authorisation header when testing protected routes.

For example, if you're sending a POST request to the /author/blog route, include the article data in the request body.

First, you'll need to start the server by running the following command in the terminal:

npm start

Next, create a new user. Send a POST request to the /auth/signup route and include the user data in the request body like this:

{
  "email": "doe@example.com",
  "password": "Password1",
  "firstname": "jon",
  "lastname": "doe",
}

If successful, you'll get a success response:

{
    "message": "Signup successful",
    "user": {
        "firstname": "jon",
        "lastname": "doe",
        "email": "doe@example.com",
    }
}

Next, login. Send a POST request to the /auth/login route and include the user data in the request body like this:

{
  "email": "doe@example.com",
  "password": "Password1",
}

If successful, you'll get a success response with a token:

{
    "message": "Login successful",
    "token": "sjlkafjkldsf.jsdntehwkljyroyjoh.tenmntiw"
}

Finally, send POST request to the /author/blog route and include the article data in the request body like this:

{
    "title": "testing the routes",
    "body": "This is the body of the article",
    "description": "An article",
    "tags": "blog,test",
}

You should get a 401(Unauthorised) status code. Try again, but add an Authorization header with a bearer token Bearer {token}. Replace {token} with the token you got after logging in. You should get a success response:

{
    "message": "Article created successfully",
    "article": {
        "title": "testing the routes",
        "description": "An article",
        "tags": [
            "blog",
            "test"
        ],
        "author": "6366b10174282b915e1be028",
        "timestamp": "2022-11-05T20:52:40.573Z",
        "state": "draft",
        "readCount": 0,
        "readingTime": "1 min",
        "body": "This is the body of the article",
        "_id": "6366cd18b34b65410bc391db"
    }
}

Test the other routes.

That's it! With the API routes and controllers implemented and tested, we now have a fully-functional blog API. In the next article, we'll cover additional topics such as error logging and deploying our API. Stay tuned!

Building a Blog API with Node.js: Authentication and Validation (Part 3)

Precious Abubakar — Mon, 09 Jan 2023 15:18:53 +0000

In the previous articles in this series, we designed our API, implemented the data models and established the database connection. Before we start building the actual API, we'll cover two topics that are important for any API:

Authentication
Validation

Let's start by installing the dependencies required for this section:

npm install joi jsonwebtoken passport passport-jwt passport-local passport-local-mongoose

Authentication with Passport.js

To authenticate users in our API, we'll be using the popular Passport.js library. When a user logs in, we'll generate a JWT token for the user. The token will be used to authorise the user's requests to the API.

In the /authentication/passport.js file, set up the JWT strategy:

   const passport = require("passport");
   const localStrategy = require("passport-local").Strategy;
   const { UserModel } = require("../models");

   const JWTstrategy = require("passport-jwt").Strategy;
   const ExtractJWT = require("passport-jwt").ExtractJwt;

   passport.use(
     new JWTstrategy(
       {
          secretOrKey: process.env.JWT_SECRET,
          jwtFromRequest: ExtractJWT.fromAuthHeaderAsBearerToken()
       },
    async (token, done) => {
       try {
           return done(null, token.user);
        } catch (error) {
           done(error);
        }
    }
    )
   );

The JSON Web Token (JWT) strategy that allows us to authenticate users by verifying their JWT. To use this strategy, we pass in a secret key (which we have stored in our .env file) and a fucntion. The ExtractJWT.fromAuthHeaderAsBearerToken() method will extract the JWT from the Authorization header of the request as a Bearer token. If the JWT is found, it will be decoded and passed to the function along with the done function. The function will check the user object in the JWT to see if it is valid. If it's valid, it will call the done function with the user object, indicating that the user has been authenticated, else it will call the done function with an error.

For the /signup route, we'll set up a local strategy, which uses the passport-local module to authenticate users with a username (in this case, their email address) and password. When a user signs up, we'll create a new User document in the database and return it to Passport.

   passport.use(
    "signup",
    new localStrategy(
        {
            usernameField: "email",
            passwordField: "password",
            passReqToCallback: true
        },
        async (req, email, password, done) => {
            try {

            const user = await UserModel.create({ ...req.body, password });

                return done(null, user);
            } catch (error) {
                done(error);
            }
        }
    )
   );

The login strategy will also use the passport-local module. When a user logs in, we search the database for a matching email address and verify that the user exists in the database. If the login is successful, we return the user object to Passport.

   passport.use(
    "login",
    new localStrategy(
        {
            usernameField: "email",
            passwordField: "password",
            passReqToCallback: true
        },
        async (req, email, password, done) => {
            try {
                const user = await UserModel.findOne({ email });

                if (!user) {
                    return done(null, false, { message: "User not found" });
                }

                return done(null, user, { message: "Logged in Successfully" });
            } catch (error) {
                return done(error);
            }
        }
    )
);

We still need to verify the user's password. In /src/models/user.models.js, create a method called isValidPassword() in the User model.

UserModel.methods.isValidPassword = async function (password) {
    const user = this;

    const match = await bcrypt.compare(password, user.password);

    return match;
};

isValidPassword takes password as an argument and compares it to the user's hashed password using bcrypt's compare method. The method returns a boolean value indicating whether the passwords match.

In src/authentication/passport.js, call isValidPassword to validate the user's password in the login strategy:

const validate = await user.isValidPassword(password);

if (!validate) {
    return done(null, false, {message: "Wrong Password" });
}

The complete file should look like this:

const passport = require("passport");
const localStrategy = require("passport-local").Strategy;
const { UserModel } = require("../models");

const JWTstrategy = require("passport-jwt").Strategy;
const ExtractJWT = require("passport-jwt").ExtractJwt;

passport.use(
    new JWTstrategy(
        {
            secretOrKey: process.env.JWT_SECRET,
            jwtFromRequest: ExtractJWT.fromAuthHeaderAsBearerToken()
        },
        async (token, done) => {
            try {
                return done(null, token.user);
            } catch (error) {
                done(error);
            }
        }
    )
);

passport.use(
    "signup",
    new localStrategy(
        {
            usernameField: "email",
            passwordField: "password",
            passReqToCallback: true
        },
        async (req, email, password, done) => {
            try {

                const user = await UserModel.create({ ...req.body, password });

                return done(null, user);
            } catch (error) {
                done(error);
            }
        }
    )
);

passport.use(
    "login",
    new localStrategy(
        {
            usernameField: "email",
            passwordField: "password",
            passReqToCallback: true
        },
        async (req, email, password, done) => {
            try {
                const user = await UserModel.findOne({ email });

                if (!user) {
                    return done(null, false, { message: "User not found" });
                }

                const validate = await user.isValidPassword(password);

                if (!validate) {
                    return done(null, false, { message: "Wrong Password" });
                }

                return done(null, user, { message: "Logged in Successfully" });
            } catch (error) {
                return done(error);
            }
        }
    )
);

Validation with Joi

To validate user input, we'll be using the Joi library. Joi provides a simple, yet powerful way to define and validate data structures in Node.js applications.

In the /validators directory, create a file called author.validator.js:

const Joi = require("joi");

const newArticleValidationSchema = Joi.object({
    title: Joi.string().trim().required(),
    body: Joi.string().trim().required(),
    description: Joi.string().trim(),
    tags: Joi.string().trim(),
});

const updateArticleValidationSchema = Joi.object({
    title: Joi.string().trim(),
    body: Joi.string().trim(),
    description: Joi.string().trim(),
    tags: Joi.string().trim(),
    state: Joi.string().trim(),
});

const newArticleValidationMW = async (req, res, next) => {
    const article = req.body;
    try {
        await newArticleValidationSchema.validateAsync(article);
        next();
    } catch (error) {
        return next({ status: 406, message: error.details[0].message });
    }
};

const updateArticleValidationMW = async (req, res, next) => {
    const article = req.body;
    try {
        await updateArticleValidationSchema.validateAsync(article);
        next();
    } catch (error) {
        return next({ status: 406, message: error.details[0].message });
    }
};

module.exports = {
    newArticleValidationMW,
    updateArticleValidationMW,
};

We're exporting two middleware functions, newArticleValidationMW and updateArticleValidationMW. newArticleValidationMW uses the newArticleValidationSchema to verify that the request body of a new article request contains all of the required fields (title, body) and all the provided fields are in the correct format. If all of the fields are valid, it calls the next function to continue with the request. updateArticleValidationMW, is similar to the first, but it uses the updateArticleValidationSchema to validate the request body of an update article request.

Both functions use the validateAsync method provided by the Joi library to perform the validation. This method takes an object (the request body) and returns a promise that is rejected if the object is invalid or resolved if it is valid.

In the /validators directory, create a file called user.validator.js:

const Joi = require("joi");

const validateUserMiddleware = async (req, res, next) => {
    const user = req.body;
    try {
        await userValidator.validateAsync(user);
        next();
    } catch (error) {
        return next({ status: 406, message: error.details[0].message });
    }
};

const userValidator = Joi.object({
    firstname: Joi.string().min(2).max(30).required(),
    lastname: Joi.string().min(2).max(30).required(),
    email: Joi.string().email({
        minDomainSegments: 2,
        tlds: { allow: ["com", "net"] },
    }),
    password: Joi.string()
        .pattern(new RegExp("^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})"))
        .required(),
});

module.exports = validateUserMiddleware;

In /validators/index.js:

const userValidator = require("./user.validator");
const {
    newArticleValidationMW,
    updateArticleValidationMW,
} = require("./author.validator");

module.exports = {
    userValidator,
    newArticleValidationMW,
    updateArticleValidationMW,
};

With authentication and validation in place, we're ready to start building the API routes and controllers. In the next article, we'll dive into the details of implementing the routes and controllers for our blog API. Stay tuned!

Building a Blog API with Node.js: Designing the API (Part 2)

Precious Abubakar — Sun, 08 Jan 2023 20:03:46 +0000

In part one of this series, we set up our development environment and a basic file structure. Now, let's design the API itself. In this article, we'll cover the following topics:

Deciding on the routes and functionality of our API
Defining the data models for our database
Implementing the data models
Setting up the database connection

Let's get started!

Deciding on the Routes and Functionality

The first step in designing our API is to decide on the routes and functionality we want to include.

Let's outline the requirements for our blog:

A user should be able to sign up and sign in to the blog app
A blog can be in two states: draft and published
A user should be able to get a list of published articles, whether logged in or not
A user should be able to get a published article, whether logged in or not
A logged in user should be able to create an article.
When an article is created, it should be in draft state.
The author of the article should be able to update the state of the article to published
The author of the article should be able to edit the article in draft or published state
The author of the article should be able to delete the article in draft or published state
The author of the article should be able to get a list of their articles. The endpoint should be paginated and filterable by state
Articles created should have title, cover image, description, tags, author, timestamp, state, read count, reading time and body.
The list of articles endpoint that can be accessed by both logged in and not logged in users should be paginated.
- It should be searchable by author, title and tags.
- It should also be orderable by read count, reading time and timestamp
When a single article is requested, the API should return the author's information with the blog, and the read count of the blog should increase by 1.

Considering the outlined requirements, we'll define our routes as follows:

Blog routes:
- GET /blog: Retrieve a list of all published articles
- GET /blog/:article_id: Retrieve a single article by its ID
Author routes: We want only authenticated users to have access to these routes and all of the CRUD operations.
- GET /author/blog: Retrieve a list of all published articles created by the user.
- POST /author/blog: Create a new article
- PATCH /author/blog/edit/:article_id: Update an article by its ID
- PATCH /author/blog/edit/state/:article_id: Update an article's state
- DELETE /author/blog/:article_id: Delete an article by its ID
Auth routes: for managing user authentication.
- POST /auth/signup: Register a new user
- POST /auth/login: Log in an existing user

Defining the Data Models

With the routes defined, we can start thinking about the data models for our database. A data model is a representation of the data that will be stored in the database and the relationships between that data. We'll be using Mongoose to define our schema.

We will have two data models: Blog and User.

User

field	data_type	constraints
firstname	String	required
lastname	String	required
email	String	required, unique, index
password	String	required
articles	Array, [ObjectId]	ref - Blog

Blog

field	data_type	constraints
title	String	required, unique, index
description	String
tags	Array, [String]
imageUrl	String
author	ObjectId	ref - Users
timestamp	Date
state	String	required, enum: ['draft', 'published'], default:'draft'
readCount	Number	default:0
readingTime	String
body	String	required

Mongoose has a method called populate(), which lets you reference documents in other collections. populate() will automatically replace the specified paths in the document with document(s) from other collection(s). The User model has its articles field set to an array of ObjectId's. The ref option is what tells Mongoose which model to use during population, in this case the Blog model. All _id's we store here must be article _id's from the Blog model. Similarly, the Blog model references the User model in its author field.

Implementing the data models

In /src/models, create a file called blog.model.js and set up the Blog model:

const mongoose = require("mongoose");
const uniqueValidator = require('mongoose-unique-validator');

const { Schema } = mongoose;

const BlogSchema = new Schema({
    title: { type: String, required: true, unique: true, index: true },
    description: String,
    tags: [String],
    author: { type: Schema.Types.ObjectId, ref: "Users" },
    timestamp: Date,
    imageUrl: String,
    state: { type: String, enum: ["draft", "published"], default: "draft" },
    readCount: { type: Number, default: 0 },
    readingTime: String,
    body: { type: String, required: true },
});

// Apply the uniqueValidator plugin to the blog model
BlogSchema.plugin(uniqueValidator);

const Blog = mongoose.model("Blog", BlogSchema);

module.exports = Blog;

The title field is defined as a required string and must be unique across all documents in the collection. The description field is defined as a string, and the tags field is defined as an array of strings. The author field is defined as a reference to a document in the users collection, and the timestamp field is defined as a date. The imageUrl field is defined as a string, the state field is defined as a string with a set of allowed values (either "draft" or "published"), and the readCount field is defined as a number with a default value of 0. The readingTime field is defined as a string, and the body field is defined as a required string.

mongoose-unique-validator is a plugin that adds pre-save validation for unique fields within a Mongoose schema. It will validate the unique option in the schema and prevent the insertion of a document if the value of a unique field already exists in the collection.

In /src/models, create a file called user.model.js and set up the User model:

const mongoose = require("mongoose");
const uniqueValidator = require("mongoose-unique-validator");
const bcrypt = require("bcrypt");

const { Schema } = mongoose;

const UserModel = new Schema({
    firstname: { type: String, required: true },
    lastname: { type: String, required: true },
    email: {
        type: String,
        required: true,
        unique: true,
        index: true,
    },
    password: { type: String, required: true },
    articles: [{ type: Schema.Types.ObjectId, ref: "Blog" }],
});

// Apply the uniqueValidator plugin to the user model
UserModel.plugin(uniqueValidator);

UserModel.pre("save", async function (next) {
    const user = this;

    if (user.isModified("password") || user.isNew) {
        const hash = await bcrypt.hash(this.password, 10);

        this.password = hash;
    } else {
        return next();
    }
});

const User = mongoose.model("Users", UserModel);

module.exports = User;

The firstname and lastname fields are defined as required strings, and the email field is defined as a required string and must be unique across all documents in the collection. The password field is defined as a required string, and the articles field is defined as an array of references to documents in the Blog collection.

The pre hook is used to add a function that will be executed before a specific Mongoose method is run. The pre-save hook here hashes the user's password with the npm module bcrypt, before the user document is saved to the database.

Setting Up the Database Connection

Now that we have our routes and data models defined, it's time to set up the database connection.

Set up your MongoDB database and save the connection url in your .env file.
Run the following command to install the npm package mongoose:

npm install --save mongoose

Create a file called db.js in the /database directory. In /database/db.js, set up the database connection using Mongoose:

const mongoose = require('mongoose');

const connect = (url) => { 
mongoose.connect(url || 'mongodb://[localhost:27017](http://localhost:27017)')

mongoose.connection.on("connected", () => { 
    console.log("Connected to MongoDB Successfully"); 
});

mongoose.connection.on("error", (err) => { 
    console.log("An error occurred while connecting to MongoDB");
    console.log(err);    
}); 
}

module.exports = { connect };

The connect function takes an optional url argument, which specifies the URL of the database to connect to. If no URL is provided, it defaults to 'mongodb://localhost:27017', which connects to the MongoDB instance running on the local machine at the default port (27017).

Create an index.js file in the /database directory:

const database = require("./db");

module.exports = {
  database,
};

Now that we have the database connection set up, in the next article, we'll dive into two important concepts- authentication and data validation. Stay tuned!

Building a Blog API with Node.js: Introduction and Setting up the Server (Part 1)

Precious Abubakar — Sun, 08 Jan 2023 18:16:43 +0000

Introduction

In this series, we'll be building a simple blog API using Node.js. If you're not familiar with what an API is, it stands for "Application Programming Interface" and it allows different software systems to communicate with each other. In this case, our blog API will allow us to create, read, update, and delete blog posts, as well as manage user authentication.

Why build a blog API with Node.js? Node.js is a popular, open-source runtime environment for executing JavaScript code outside of a browser. It has a large, active community of developers and a wealth of libraries and frameworks that make it easy to build scalable, high-performance web applications.

In this first article, we'll cover the initial steps of setting up our development environment, creating a new project and setting up our server. Let's get started!

Prerequisites

Here's what we'll need:

Node.js: You can download the latest version of Node.js from the official website and follow the installation instructions. This will also install the Node.js package manager (npm), which we'll use to install additional packages.
MongoDB: We'll be using a MongoDB database to store our data. You can follow the installation instructions on the official website.
A code editor: You can use any code editor that you prefer, such as Visual Studio Code, Sublime Text, or Atom.
A terminal: We'll be using the integrated VS code terminal to run commands and interact with our project, but you can use your preferred terminal.
A basic understanding of JavaScript, APIs, databases and other web development concepts. If you're new to these topics, it might be helpful to brush up on your knowledge before diving into this tutorial.

Setting up the Development Environment

To create a new project, open up your terminal and navigate to the directory where you want to create your project. Then, run the following command:
```
npm init -y
```
This will create a package.json file in your project directory, which is used to manage dependencies and scripts for your project. The -y flag accepts all the default options, so you don't have to manually enter them.

Next, run the following command to install these dependencies:

npm install --save express dotenv cors express-rate-limit helmet express-fileupload

File Structure

Now that we have our dependencies installed, let's create the file structure for our project. Create the following directories and files in your project directory:

/src: This is the main directory for our project. It will contain all the source code for our application.
/src/authentication: This directory will contain the code related to user authentication, such as password hashing and JWT generation.
/src/config: This directory will contain configuration files for our application, such as the database connection string and server port number.
/src/controllers: This directory will contain the code for the controllers of our API. Controllers handle incoming requests and send responses to the client.
/src/database: This directory will contain the code for connecting to and interacting with the database.
/src/loggers: This directory will contain the code for logging events in our application.
/src/models: This directory will contain the code for the database models of our application. Models represent the data stored in the database and provide an interface for interacting with that data.
/src/routes: This directory will contain the code for the API routes. Routes define the endpoints of our API and specify the HTTP methods (e.g., GET, POST) that can be used to access them.
/src/services: This directory will contain any service objects or utility functions that are used throughout our application.
/src/validators: This directory will contain the code for validating input data.
app.js: This file will contain the middleware and routers for the server.
index.js: This is the entry point for our application. It will contain the code for starting the server and connecting to the database.
package.json: This file contains metadata for the API. The start script should be: "start": "node index.js".

Setting Up Environment Variables

Let's set up the environment variables we'll need for this project. As we build, it will become clear why each variable is needed.

Avoid exposing your API secrets, as it is a security risk. If you're using version control, you can set up a config file that you can push without exposing any secrets, or you may create a .env.example showing the variable names only, with no values.

Create an index.js file in /src/config:

require("dotenv").config();

module.exports = {
    PORT: process.env.PORT,
    MONGODB_CONNECTION_URL: process.env.MONGODB_CONNECTION_URL,
    JWT_SECRET: process.env.JWT_SECRET,
    CLOUDINARY_URL: process.env.CLOUDINARY_URL,
};

In the root directory, create a .env file. We'll update the values as we build:
```
PORT=5000
MONGODB_CONNECTION_URL=
JWT_SECRET=
CLOUDINARY_URL=
```

Setting up the server

In the app.js file, add the following code:

const express = require("express");
const rateLimit = require("express-rate-limit");
const helmet = require("helmet");
const cors = require("cors");
const fileUpload = require("express-fileupload");

const CONFIG = require("./src/config");

const app = express();

app.use(cors());

const limiter = rateLimit({
    windowMs: 15 * 60 * 1000,
    max: 100,
    standardHeaders: true,
    legacyHeaders: true,
    message: "Too many requests, please try again after 15 minutes",
});
app.use(limiter);
app.use(helmet());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(
  fileUpload({
    createParentPath: true,
    useTempFiles: true,
    tempFileDir: "/tmp/",
  })
);

app.get("/", (req, res) => {
    return res.json({ status: true });
});

// 404 error handler
app.use("*", (req, res) => {
    return res.status(404).json({ message: "Route not found" });
});

// Error Handler
app.use(function (err, req, res, next) {
    console.log(err.message);
    res.status(err.status || 500).send("Oops, something failed");
});

module.exports = app;

We've set up the following middleware:

cors allows cross-origin resource sharing, which means that our API can be accessed from a different domain.

Following that, we have a rate-limiting middleware that limits the number of requests a user can make within a certain period. This helps protect against malicious users trying to overwhelm the server with requests:

const limiter = rateLimit({
    windowMs: 15 * 60 * 1000,
    max: 100,
    standardHeaders: true,
    legacyHeaders: true,
    message: "Too many requests, please try again after 15 minutes",
});
app.use(limiter);

We also have the helmet middleware, which helps secure the API by setting various HTTP headers.

Then, we have the following middleware which allows the API to process JSON and URL-encoded data in the body of requests:

app.use(express.json()); 
app.use(express.urlencoded({ extended: true }));

Finally, we have the fileUpload middleware, which allows the API to handle file uploads:

app.use(fileUpload({ 
    createParentPath: true, 
    useTempFiles: true, 
    tempFileDir: "/tmp/", 
}));

In the index.js file, add the following code:

const app = require("./app");

const CONFIG = require("./src/config");

app.listen(CONFIG.PORT, () => {
    console.log(`server listening on port ${CONFIG.PORT}`);
});

Now we're ready to start coding the individual components of our blog API. In the next article, we'll begin with the database models and establish a connection to the database. Stay tuned!

How to Reset a Local Git branch to a Remote Branch

Precious Abubakar — Sun, 23 Oct 2022 20:44:02 +0000

Git is a free and open-source distributed version control system that makes collaboration seamless. The Git feature that really makes it stand out is its branching model. Git allows and encourages you to have multiple local branches that can be entirely independent of each other.

Keeping your local branches in sync with the remote is a common problem faced by developers, and the obvious solution is $ git pull <remote> <branch> which incorporates changes from the remote branch into the local branch. However, sometimes you don't want to merge the remote changes with your local changes, because, for one reason or the other, you want to have a copy of the remote changes in an unaltered state, without interference from your own local changes.

In this article, you will learn how to reset a local branch to a remote branch using git fetch and git reset. If you’re confused by some of the terminology (e.g. remote), read this.

Prerequisite

Basic knowledge of git

Understanding the Problem

Picture this: you're contributing to a group project and you've made some changes locally. Contributor B refactors the codebase and merges the changes to the upstream/main branch. You want to make sure this new update works before you integrate it into your local main branch, so you create a branch $ git checkout -b test and pull from upstream $ git pull upstream main.

What happens? You either get merge conflicts or an updated version of your code with both local and upstream changes merged. But this wasn't what you were hoping to achieve, so how can you pull the upstream changes while discarding everything that currently exists on the test branch?

First, let's take a look at how git pull works.

Git Pull

Git pull incorporates changes from a remote repository into the current branch. Git pull does two things- fetching and merging. More precisely, git pull runs git fetch and then depending on configuration options or command line flags, will call either git rebase or git merge.

Git Fetch: downloads objects and refs from another repository. In this context, it downloads the changes from our upstream/main branch.
Git Merge: incorporates changes from the latest commits into the current branch. This is the step we want to avoid since we don't actually want to merge the two histories, we only want to keep one.

In this example, the current branch is "test", and by running git push, we are merging the changes from upstream/main into our local test branch.

TLDR: The Solution

We can fetch the remote changes from upstream/main using git fetch, and reset the local branch using git reset.

Git Reset: resets the current branch to the specified state. There are several configurations but we'll be using the --hard flag. --hard resets the index and working tree. Any changes to tracked files in the working tree are discarded. Any untracked files or directories in the way of writing any tracked files are simply deleted.

Reset Local Branch to Remote Using Git Reset

On your local repository, checkout to a new branch

$ git checkout new-branch
Fetch changes from remote (in this example, we are fetching from the upstream/main branch but you can change this to suit your use case)

$ git fetch upstream main
Reset local branch to remote branch

$ git reset --hard upstream/main
clean up any untracked changes

$ git clean -xdf

The -x flag removes ignored files.

The -d flag removes untracked folders.

The -f flag removes untracked files.

Conclusion

There are other methods you can use to solve this problem, and this article by Brian Dordevic talks about them. Another great resource you can look at is this post on freecodecamp.

Now that you know the basics about git pull, git fetch, git merge and git reset, you can find out more about how they really work and all the different ways you can use them in the git documentation.

Using git can be overwhelming, but you can take comfort in the fact that nobody has all the git commands memorized. It's okay to have issues occasionally, what matters is that you can figure them out and learn something in the process. You can always read the documentation, ask questions or find answers on Stackoverflow. We all do. 😉

Credits

Open Source Contribution: Why It's A Great Idea

Precious Abubakar — Sat, 04 Jun 2022 10:58:10 +0000

What is Open Source Software?

Imagine a Chef writing a recipe book. He uploads his manuscript to Google Drive, grants write access, and shares the link so that other chefs can contribute to it. Open source software is software with source code that anyone can inspect, modify, and enhance. If you have a smartphone or a PC, chances are you've used open-source software once or twice e.g. Mozilla Firefox, VLC media player, WordPress, Ubuntu, Blender, etc.

Who Can Contribute to Open Source Software?

Contrary to popular belief, you don't have to write code to contribute to open source. Documentation, discussions, UX, advocacy, and other forms of contribution are often overlooked and equally important. Therefore, anyone with an interest can contribute to Open Source.

Why Should I Contribute to Open Source Software?

I asked a few Open Source contributors in CHAOSS Community and here's why they think you should consider contributing to Open Source today:

Ruth Ikegah, Badging Initiative Maintainer and Member of DEI Working group :

Collaboration: The transparency in Open Source fosters collaboration. By contributing to Open Source, you get to work with like-minded folks to build up an idea from scratch to a live product.

Elizabeth Barron, CHAOSS Community Manager :

Learn valuable tech skills through practice (doesn’t have to be just code!)

meet and connect with interesting people from around the world who have similar interests

Learn to collaborate and work asynchronously with distributed teams (which is a very helpful skill for the workplace)

Use your skills to make someone’s life better (especially if the project is for a non-profit, or if it has a socially impactful or DEI aspect to it)

Build a portfolio of your work to show potential employers

Help others grow their own skills by welcoming them to a project and helping them find their way

How Can I Become an Open Source Contributor?

You can find a curation of Open Source projects at Up For Grabs, Aviyel and similar platforms. Once you've identified a project you would like to contribute to, you should read their documentation (they usually have a contribution guide). Most of these projects have communities centered around them, it is best to join the community for support.

You don't need to be an expert to begin, they usually welcome beginners and direct you towards beginner-friendly tasks. However, to be an amazing open-source contributor, you must be able to communicate effectively, dedicate some time, and be open to diversity and inclusivity, as you would be collaborating with people of diverse ethnicity and beliefs.

You don't typically get paid for Open Source contributions, but some mentorship and internship programs pay people to contribute, such as Google Season of Docs, Google Summer of Code, Conthributhon by SheCodeAfrica and Outreachy. This is also a great way to get involved if you're just starting in your field and you need guidance.

Conclusion

Contributing to Open Source Software can seem daunting, and that is normal. Lots of Open Source Contributors felt the same way too. I contributed to Open Source for the first time last month, and here's how that went. Read how Rizel Scarlett conquered their fear of contributing to Open Source. Rizel also shared quick tips to navigating Open Source like a pro.

Contributhon 2022 by SheCodeAfrica

Precious Abubakar — Sat, 28 May 2022 00:02:09 +0000

Contributhon is a 2-month Open Source Bootcamp designed by SheCodeAfrica to pair mentors from different global open source organizations with African women in tech who get to work with them on selected projects within the organization. The participating mentoring organizations for this cohort were CHAOSS, Layer5, Jenkins, Moja Global, and Coil.

After joining Contributhon as a mentee last month, I was assigned to CHAOSS, where I contributed to open source for the first time. CHAOSS is an open source project at the Linux Foundation focused on creating analytics and metrics to help define community health.
I worked with a fellow mentee- Iyimide, and three mentors from CHAOSS- Ruth Ikegah, Elizabeth Barron, and Matt Snell. As this cohort of Contributhon comes to an end, I have documented a summary of my activities in the last couple of weeks.

Overview

I worked on the CHAOSS Newcomer Slack Bot Project with Iyimide.
Our tasks included:

Determine the best framework for writing the Slack bot.
Use CHAOSS’s GitHub repository to host the code for the bot.
Include tests for the bot, if possible.
Include comments in the code that will help the next maintainer understand how the bot works.
Work with mentors at CHAOSS for bot content, and bring your own ideas!
At the end of the project, document the information for installing, maintaining, adding to bot content, or troubleshooting.

My Contribution

After doing research and testing, and with some guidance from our mentors, we set up the project repo(which we currently still maintain) and set up CI/CD. Afterward, we built and deployed the bot.

See my pull requests

After completing the initial phase of our project, I focused on writing the documentation

CHAOSS Slack Bot Documentation

Challenges

I had my doubts about the project initially because it was not something I was familiar with. Also, it was my first time contributing to open-source after several previous attempts which failed because it was all very confusing. However, the team was great. I got (and I'm still getting) all the support and encouragement I needed from my mentors and my co-mentee. Any confusion on my part was quickly cleared up.

Experience gained

Some of the skills/concepts I learned/improved on during this program are:

Continuous integration/Continuous Deployment
Unit testing
Technical writing
Troubleshooting with Git
Developer sign-off
Effective communication

Improvement Suggestions

This cohort was great, and the next cohort would be even better with more presentations from resourced persons. They were the icing on the cake.

Next Steps

While I am still contributing to CHAOSS, I am also looking out for full-time roles and other Open Source opportunities. I hope to be a Contributhon mentor in the future.

Thank you, SheCodeAfrica 💗.