DEV Community: Kevin Wafula

Gin Tutorial: Developing a RESTful API using GIN

Kevin Wafula — Mon, 18 Sep 2023 09:39:26 +0000

Gin is a web framework written in Golang. It has high performance and good productivity. In this article, we’ll be building a crud API using Gin. This will provide a deeper understanding of the web framework.
The main topic include:

Create folder for your project
Create Packages for your code
Create the Data structures to handle data (models).
Setting up handler functions using gin
Use of the MongoDB Go Driver to connect with the MongoDB database
API endpoints and Routing
Testing using Postman

Pre-Requisites

• Working knowledge of Golang
• Have Go installed
• Some experience working with the MongoDB Go driver. If not please check out this article on the same.
• A text editor i.e. Visual Studio
• Postman or a curl tool.

1. Create folder for your project

Let’s create a project for the code.

• Go to the directory where you store your Go projects
• Create a new directory
• Finally create a module for managing your dependencies by running go mod init and include the path in which your module will exist. In this case github.com/kevin.
• Next open the project in your editor. For vs code just type code .

2. Create Packages for your code

Golang codes are organized into packages. The project structure should adhere to the go conventions.

Controllers • The controllers package contains the logic for handling HTTP requests and managing the application's business logic. • Controllers are responsible for parsing incoming HTTP requests, processing data, interacting with models (if necessary), and sending HTTP responses. • Controllers act as intermediaries between the incoming HTTP requests (handled by the router) and the application's data models. • Example functions in a controller might include handling user registration, login, data retrieval, or any other application-specific logic related to a route.
Database The database package typically contains code responsible for interacting with the application's database system.
Models • The models package contains data structures and code related to the application's data domain. • It defines the data structures that represent the core objects or entities in your application, such as User, Product, Order, etc.
Routes • The routes package is responsible for defining the application's URL routes and configuring the routing behavior. • It often contains code for setting up the router (e.g., using a package like Gorilla Mux) and mapping routes to specific controller functions. This is just a basic implementation of the MVC pattern to ensure maintainability and separation of concerns. For advanced projects you could include the middleware packages etc.

3. Create the Data structures to handle data (models).

Any API should interact with a database. In this case we’ll implement the MongoDB using the MongoDB Go Driver

In models.go import the go.mongodb.org/mongo-driver/bson/primitive package in the MongoDB Go driver provides support for BSON (Binary JSON) primitive types. BSON is the binary serialization format used by MongoDB to store and exchange data.

Below the import statement declare an album struct. Should include the id, artist, title of album and the price.

4. Setting up handler functions with Gin

Write a handler function to return all the items.

In the controllers.go file import the necessary packages.

Declare a variable

We’ve declared a variable called AlbCollection that points to the mongo.Collection as its type.
This variable will hold a reference to a MongoDB collection, which is a place where you can store and query documents (data) in MongoDB. albums is the name of the mongo DB collection.

Next, copy this function below the above.

In the above code, you:
• Write a function called GetAlbums that takes *gin.Context as its parameter.
• Create a context with a timeout of 100 seconds
• Use the AlbCollection to find all documents in the collection
• Create a slice to hold the albums retrieved from the database and handle any errors
• Loop through the cursor to decode and collect each album and append the decoded album to the albums slice
• Finally, return the list of albums as a JSON response with an HTTP status of 200 (OK)

Write a function to post items into the database

In this code, you:
• Write a handler function to handle the creation of a new album resource in a web application using the Gin web framework and MongoDB for data storage.
• In the function, you create a newAlbum variable of type models. Album and bind the incoming JSON request body to the newAlbum variable
• Next, you generate a new ObjectID for the album
• Finally, insert the newAlbum into the **AlbCollection **and handle the error if any.

Write a function to get a single item by ID

In this code, you:
• Write the GetAlbumByID function that is designed to retrieve an album from a MongoDB collection by its unique identifier (ID) and return it as a JSON response.
• In the function, you first retrieve the albumID from the URL parameter and then you create a context with a timeout of 100 seconds
• Next, parse the albumID into an ObjectID and handle any arising error.
• Then declare a variable to store the album data and query the AlbCollection to find the album with the matching ObjectID. Handle the errors if any.
• Finally, return the found album as a JSON response with an HTTP status of 200 (OK)

Write a function to modify an album

This function is designed to update an existing album in a MongoDB collection based on the provided album ID and the new album data provided in the JSON request body.
• First, you retrieve the albumID from the URL parameter and then you create a context with a timeout of 100 seconds
• Then, you declare a variable updatedAlbum to store the updated album data
• Bind the incoming JSON request body to the updatedAlbum variable and handle the errors if any.
• Parse the albumID into an ObjectID and handle the errors
• Define a filter to find the album with the specified ObjectID
• Define an update with the new album data using the "$set"operator
• Update the album in the AlbCollection and handle any errors related to writing documents in the collection.
• Return a JSON response indicating that the album has been updated

Write a function to delete an album

This function deletes an existing album from a MongoDB collection based on the provided album ID. It's likely used as a handler for an HTTP DELETE request to remove an album resource.
• First, you retrieve the albumID from the URL parameter and then you create a context with a timeout of 100 seconds
• Parse the albumID into an ObjectID and handle errors if any.
• Define a filter to find the album with the specified ObjectID

• Delete the album from the AlbCollection and handle any errors related to the deletion.
• Check if any album was deleted and if no album was deleted (not found), return a not found response
• Return a JSON response indicating that the album has been deleted

5. Write the database logic

In the database.go file first import the following packages.

Then add the following code:

The code above has two functions that provide the logic for connecting to the mongo database and creating a reusable client instance and collection handler for a Go web application using the MongoDB Go driver respectively.
The ConnectDB function establishes a connection to the MongoDB database and returns a client instance.
• Create a new MongoDB client with the specified server URI and if there's an error, log it and exit the application
• Create a context with a timeout of 100 seconds for the connection operation.
• Connect the client to the MongoDB server and if there's an error, log it and exit the application.
• Finally, print a message to indicate successful connection and return the client instance.

Declare a global variable named Client, which is of type **mongo.Client. It assigns the client instance returned by the **ConnectDB* function to this variable. This allows other parts of your application to use the Client variable to interact with the MongoDB database.
The OpenCollection function creates and returns a MongoDB collection handler for the specified collection name.
• Access the specified collection in the "gintest" database using the client.
• Return the collection handler.

API endpoints and Routing In your router.go file add:

In the code above we define the routes and associate them with controller functions in a web application built using the Gin web framework.

The UserRoutes function and takes one parameter, router, which is a pointer to a gin.Engine instance.
It is responsible for defining the application's routes and associating them with the appropriate controller functions.
These route definitions establish the API endpoints for your web application. When a request is made to one of these endpoints, Gin will call the associated controller function from the controllers package, which is where the actual request handling and business logic take place.

Finally in the main.go file add the following:

The code above is the main entry point for a Go web application using the Gin web framework. It sets up the application's HTTP server, configures routes, and starts the server.
• Create a new Gin router instance
• Add Gin's built-in logger middleware for request logging
• Configure routes for the application by calling the UserRoutes function
• Finally, start the HTTP server and listen on port 8080

Run the program:

It should display this in the terminal:

7.Test the API using Postman
Create a post request:

Add the raw JSON data.

After sending the request the response should be:

Go ahead and add more data.

Get all albums

The result should be all the albums in the database.

Update an album
Update the price of one album.

The result:

Get album by id

The result:

Delete an album

It should display:

The database:

## Conclusion

This tutorial took you step by step through building a restful API using Gin framework and eventually testing using Postman. To improve your Go skills also check out the official Gin Documentation. It contains advanced topics regarding the framework.
For the MongoDB Go Driver check out my other article on the same. It has some insightful and easily explained operations in MongoDB.
Note: There are several other Go web frameworks i.e. Echo and Fiber

Integrating MONGODB in GOLANG applications

Kevin Wafula — Wed, 23 Aug 2023 19:22:18 +0000

Learning how to integrate no-sql databases with applications is becoming a must-know skill for all developers out there. Golang in particular provides the MongoDB Go Driver for easier and efficient connection with the mongo database.

In this article, I'll help you understand integration of the mongo database into Golang applications using the official MONGODB Go Driver.

Getting started with MONGODB Go Driver
CRUD operations with MongoDB
Go structs and MongoDB Mapping
Using Go structs to insert and Query MongoDB documents

Prerequisites

Some knowledge of Go
Should have installed MongoDB(version 3.6 or higher) compass locally on your desktop.
Go version 1.13 or higher installed
An IDE i.e. Visual studio

Getting started with MONGODB Go Driver
Let's install MongoDB Go driver which has functions that allow for connection to the MongoDB local database and execution of queries and operations.

The recommended method of installation is to use Go modules to install the dependency in your project. To install run

go get go.mongodb.org/mongo-driver/mongo

Creating a MongoDB client instance

Create a main.go file and import the mongoDB Go driver package using the import statement. Next, Create a mongo Client using the connect function.

Advanced authentication and configuration can be found here.

To check if a server has been found and connected use ping:

Create a MongoDB Collection
Create collection instance retrieved from a user Collection named mongo-practice.If the database does not exist MongoDB will create it automatically when the above code is run.

Performing CRUD Operations with MongoDB

After connecting to the database and creating a Collection instance, we can now execute queries in our database using Go. This topic covers the crud(create, read, update and delete) operations.

To perform the CRUD operations, you need to add the `

go.mongodb.org/mongo-driver/bson
`
package to your import statement.

The go.mongodb.org/mongo-driver/bson package provides functionalities for working with BSON (Binary JSON) data, which is the encoding used to represent documents and data in MongoDB. BSON is a binary serialization format similar to JSON but designed for more efficient storage and traversal within the MongoDB database.

Inserting Documents in the Database

InsertOne executes an insert command to insert a single document into the collection.

In your terminal, run go run main.go. It should display something like this:

**InsertMany **executes an insert command to insert more than one document into the collection.

The results should be as follows:

Read Documents from the database

MongoDB provides FindOne() and Find() to retrieve documents from the database. FindOne() returns the first document that matches the filter while Find() returns all the documents that matches the filter.

The filter parameter must be a document containing query operators and can be used to select which documents are included in the result. It cannot be nil.

Opts parameter is used to specify the options.

Define a filter to find documents where age is greater than 25:

Find all documents that match the filter and Iterate through the cursor and print each document

Retrieve the first document that matches the filter and display the results.

Run go run .

Update Documents in MongoDB

MongoDB provides Update and Replace operations to change the documents in the database.

Other operations to change documents in the mongoDB database include:

UpdateByID()
UpdateOne()
UpdateMany()
ReplaceOne()
FindOneAndUpdate()
FindOneAndReplace()

UpdateByID() updates a single document with a specified ObjectID

Rungo main.go:

We first defined the document to insert and then Inserted the document into the "users" collection. Next Defined the update operation using the $set and $inc operators and finally updated the document using UpdateByID with the inserted document's ID.

UpdateOne() and UpdateMany()

First, define a filter documents where "age" is greater than 25.

Then define the update query using $set to update the "age" field:

Execute the UpdateOne() function to update the first matching document

Execute the UpdateMany() function to update all matching documents

ReplaceOne()

Define a filter to find the document with "name" equal to "Adrian"

Create the replacement data

Execute the ReplaceOne() function to replace the fields

Run go run main.go:

FindOneAndUpdate() and FindOneAndReplace() perform the same functions as FindOne() and ReplaceOne().The only difference is that they return the result before they update or replace.

Delete Documents from the database
DeleteOne and DeleteMany functions are provided by MongoDB to delete documents from the database.

First, let's define a filter to find documents where age is greater than 25.

Next, the first document that matches the filter

Finally, delete every document that matches the filter and display the number of documents deleted.

Go structs and MongoDB Mapping

MongoDB Go driver allows for working with Go structs. You can map documents to Go structs for easier data migrations and operations.

Here’s an example of struct matching the documents in the MongoDB database:

Using structs to insert MongoDb Documents

In this case, we create a school instance and insert the instance into the collection.

The results after running main.go:

Using Go structs to query MongoDb documents

For easier data accessibility you can query the MongoDB databases with Go structs.

First, execute a query to find documents that match the filter and move the cursor to the next document.

Next, define a School struct to store the decoded document and decode the document from the cursor into the School struct.

Finally, print the information about the school

The result when you run go run .:

Throughout the article, code examples, comments, and explanations provided a step-by-step guide for developers to follow along and understand the integration process. The article highlighted not only the technical aspects but also the importance of handling errors and checking for returned results.

In conclusion, mastering the integration of MongoDB with Go applications using the MongoDB Go Driver empowers developers to build robust and efficient applications that leverage the power of NoSQL databases. This article serves as a comprehensive introduction to this integration, equipping developers with the knowledge to enhance their skill set and create effective database-driven solutions.

For detailed and advanced concepts regarding MongoDB operations and aggregate functions ,you can head over to the MongoDB Driver documentation

UNDERSTANDING DEPENDENCIES IN GOLANG

Kevin Wafula — Mon, 21 Aug 2023 14:04:40 +0000

Golang relies on external packages. The packages are considered dependencies in your project. Go provides tools to manage this dependencies to allow you to replace or update during the life time of your project.

In this article we’ll discuss:
• Locating packages on pkg.go.dev
• Importing the packages
• Enable dependency tracking by adding your code to a module.
• Add and manage external packages to your module.
• How to upgrade and downgrade versions of the imported dependencies
• Golang commands used to make dependency changes

Dependencies as modules
Managing dependencies is a critical aspect of building projects in Go. Go provides tools that manage dependencies as modules that contains the imported packages. For efficient management of dependencies Golang provides:
• A documentation browser and a package search engine (pkg.go.dev).
• Go tools for upgrading, downgrading and managing package sources
• A decentralized system for publishing modules and retrieving their code. Developers use version numbers and repository to achieve this.

Locating and importing the packages
Search pkg.go.dev to find the packages that contain the functions you need.

Find the package path and copy. Paste the path in your import statement.

import "golang.org/x/sync/errgroup"

If there’s more than one package:

import(
"golang.org/x/sync/errgroup"
"github.com/mitchellh/iochan"
)

Dependency Tracking

To enable tacking and management of your dependencies you have to put your code in a module. This creates a go.mod file at the root of your of directory. All the dependencies you’ll add will be listed in the _*go.mod *_file.

The go.mod file looks like this:

Run

`go mod tidy`

to add module requirements and sums. It also removes dependencies to the packages you’re no longer using.

Naming of Modules
To run go mod init you need to specify a module path which also serves as the module’s name. Naming modules in Go is required to take the following form: /. The prefix describes the module. In this case we’re using github.com as it is the best practice for modules you intend to publish for others to use. Descriptive text is the name of the project.
Reserved module prefixes
• example – used in Go documentation and tutorials as a module path i.e. example.com/kevin
• test – only used for a module whose code is used to locally test functions in another module i.e. go mod init test

Adding a Dependency
To add a dependency for a package in your module run go get . In the case of a specific dependency, you need to specify its module path. I.e. go get example.com/themodule .This command authenticates each module it downloads and makes sure it is unchanged. In case of any changes it will provide a security error.
You can also get a specific version of a module by specifying the version of the module.

`go get example.com/themodule@v1.4`

or the latest version by

`go get example.com/themodule@latest`

Checking for available updates
Use the go list command to display all your module dependencies. The command

`go list –m –u all`

lists all the dependences of your current module with their latest version.

In the above article I sought to summarize all the important information regarding dependencies. There are other detailed aspects of dependencies like developing and testing against unpublished code and getting a specific commit using a repository Identifier that are covered in detail by Go official documentation.

SENDING EMAILS IN DJANGO: A BEGINNER'S GUIDE

Kevin Wafula — Fri, 14 Apr 2023 07:45:43 +0000

Sending Emails in Django.

Django is a popular Python web framework that provides a robust set of tools for building web applications. One key feature of web applications is the ability to send and receive email messages. Sending email messages in Django can be easily accomplished by built-in SMTP and EmailMessage classes. In this article, I'll introduce you to sending emails in Django and the best practices for going about it, which will accelerate and make email delivery easier.

In addition to the built-in EmailMessage and SMTP classes, Django includes support for other email-related features, such as email templates, email attachments, and email logging. With these tools, developers can customize the look and feel of their email messages, attach files to their emails, and track email activity for debugging and analysis purposes. By using Django's email-related features, developers can build web applications that are not only powerful and feature-rich but also capable of sending and receiving email messages with ease.

Prerequisites

You’ll be best equipped for this tutorial if you already have a solid foundation in some web application concepts. You should understand how HTTP requests and responses, create a Django development environment and start a Django project.

Using **send_mail() to send email messages**

Let's kick off our tutorial with a simple code to show how to send an email.

Here is a detailed list of parameters of send_mail ():
• subject- the subject of your email
• from_email – the sender
• recipient_list *– the receiver
• *_message _– the body of the email
• fail_silently – Boolean, If True send_mail will not raise an exception error.
• html_message – if provided the resulting email will be an alternative email message as text/plain content type while the html message will be the text/html content type.
The mail is sent using the SMTP host and port specified in the settings.py of the main project. To authenticate the SMTP server EMAIL_HOST_USER and EMAIL_HOST_PASSWORD are used. EMAIL_USE_TLS and EMAIL_USE_SSL are then used to provide a secure connection. DEFAULT_FROM_EMAIL is used to provide a default sender email.

Sending Mass emails using send_mass_mail()

It is more or less the same as send_mail () but here you have to use a datatuple parameter that holds the messages.

The main difference between send_mail () and send_mass_mail () is that send_mail () opens a connection with the SMTP server each time it is executed while send_mass_mail () uses a single connection to send all its messages.

Using _EmailMessage _class to send emails

Both send_mail() and send_mass_mail() make use of EmailMessage class. But most of the EmailMessage features are not available to send_mail ().
_EmailMessage _is responsible for creating the email message itself.

The parameters include body, from_email (), to, bcc, attachments, headers, cc, and reply_to in that order.
The EmailMessage also has methods like recipients (), attach (), and many more

Sending emails to the console or terminal

During development in Django, it can be useful to send email messages to the console or terminal instead of sending them to real email addresses. This allows developers to test email functionality without the need for a real email server or the risk of accidentally sending emails to real users. Luckily, Django provides a simple way to redirect email messages to the console using the EmailBackend class.
To use the EmailBackend class, developers can update the EMAIL_BACKEND setting in their Django settings file to point to the console backend:

By using the console backend, developers can easily test their email functionality during development without the need for a real email server or the risk of accidentally sending emails to real users.

Conclusion

In conclusion, sending emails in Django is a straightforward process that can be accomplished using the built-in _EmailMessage _and _SMTP _classes. By leveraging these classes and other email-related features provided by Django, developers can send personalized email messages to users, notify administrators of errors or system events, and perform other email-related tasks.

During development, Django also provides a convenient way to redirect email messages to the console or terminal, allowing developers to test their email functionality without the need for a real email server or the risk of accidentally sending emails to real users.

Overall, Django's email-related features provide a powerful and flexible toolset for building web applications that are capable of sending and receiving email messages with ease. Whether you're sending simple text emails or complex HTML messages with attachments, Django's email functionality can help you communicate with your users effectively and efficiently.
Attributions
Credits
• Django Documentation
• Geeks for geeks