The demand for mobile and web applications to support file uploads ranging from images and videos to documents like excel, CSV, and PDF has increased tremendously over the years. It is paramount that we have the required knowledge to integrate file upload support into our applications.
This post will discuss adding media upload support to a REST API using Golang’s Gin-gonic framework and Cloudinary. At the end of this tutorial, we will learn how to structure a Gin-gonic application, integrate Cloudinary with Golang and upload media files to Cloudinary using remote URLs and local file storage.
Gin-gonic, popularly known as Gin, is an HTTP web framework written in Golang with performance and productivity support. Gin uses a custom version of HttpRouter, a lightweight, high-performance HTTP request router that navigates through API routes faster than most frameworks out there.
Cloudinary offers a robust visual media platform to upload, store, manage, transform, and deliver images and videos for websites and applications. The platform also offers a vast collection of software development kits (SDKs) for frameworks and libraries.
You can find the complete source code in this repository.
Prerequisites
The following steps in this post require Golang experience. Experience with Cloudinary isn’t a requirement, but it’s nice to have.
We will also be needing the following:
- A Cloudinary account to store the media files. Signup is completely free.
- Postman or any API testing application of your choice.
Let’s code
Getting Started
To get started, we need to navigate to the desired directory and run the command below in our terminal:
mkdir gin-cloudinary-api && cd gin-cloudinary-api
This command creates a gin-cloudinary-api
folder and navigates into the project directory.
Next, we need to initialize a Go module to manage project dependencies by running the command below:
go mod init gin-cloudinary-api
This command will create a go.mod
file for tracking project dependencies.
We proceed to install the required dependencies with:
go get -u github.com/gin-gonic/gin github.com/cloudinary/cloudinary-go github.com/joho/godotenv github.com/go-playground/validator/v10
github.com/gin-gonic/gin
is a framework for building web application.
github.com/cloudinary/cloudinary-go
is a library for integrating Cloudinary.
github.com/joho/godotenv
is a library for managing environment variable.
github.com/go-playground/validator/v10
is a library for validating structs and fields.
Application Entry Point
With the project dependencies installed, we need to create main.go
file in the root directory and add the snippet below:
package main
import "github.com/gin-gonic/gin"
func main() {
router := gin.Default()
router.GET("/", func(c *gin.Context) {
c.JSON(200, gin.H{"data": "Hello from Cloudinary"})
})
router.Run("localhost:6000")
}
The snippet above does the following:
- Import the required dependencies.
- Initialize a Gin router using the
Default
configuration. TheDefault
function configures Gin router with default middlewares (logger and recovery). - Use the
Get
function to route to/
path and a handler function that returns a JSON ofHello from Cloudinary
. - Use the
Run
function to attach therouter
to an http.Server and starts listening and serving HTTP requests onlocalhost:6000
.
Next, we can test our application by starting the development server by running the command below in our terminal.
go run main.go
Modularization in Golang
It is essential to have a good folder structure for our project. Good project structure simplifies how we work with dependencies in our application and makes it easier for us and others to read our codebase.
To do this, we need to create configs
, services
, controllers
, helper
, models
, and dtos
folder in our project directory.
PS: The go.sum
file contains all the dependency checksums, and is managed by the go
tools. We don’t have to worry about it.
configs
is for modularizing project configuration files
services
is for modularizing application logic. It helps keep the controller clean.
controllers
is for modularizing application incoming requests and returning responses.
helper
is for modularizing files used for performing computation of another file.
models
is for modularizing data and database logics.
dtos
is for modularizing files describing the response we want our API to give. This will become clearer later on.
Data Transfer Object (DTO) is simply an object that transfers data from one point to another.
Setting up Cloudinary
With that done, we need to log in or sign up into our Cloudinary account to get our Cloud Name, API Key, and API Secret.
Next, we need to create a folder to store our media uploads. To do this, navigate to the Media Library tab, click on the Add Folder Icon, input go-cloudinary
as the folder name and Save.
Setup Environment Variable
Next, we need to include the parameters from our dashboard into an environment variable. To do this, first, we need to create a .env
file in the root directory, and in this file, add the snippet below:
CLOUDINARY_CLOUD_NAME=<YOUR CLOUD NAME HERE>
CLOUDINARY_API_KEY=<YOUR API KEY HERE>
CLOUDINARY_API_SECRET=<YOUR API SECRET HERE>
CLOUDINARY_UPLOAD_FOLDER=go-cloudinary
Load Environment Variable
With that done, we need to create helper functions to load the environment variables using the github.com/joho/godotenv
library we installed earlier. To do this, we need to navigate to the configs
folder and in this folder, create an env.go
file and add the snippet below:
package config
import (
"log"
"os"
"github.com/joho/godotenv"
)
func EnvCloudName() string {
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
return os.Getenv("CLOUDINARY_CLOUD_NAME")
}
func EnvCloudAPIKey() string {
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
return os.Getenv("CLOUDINARY_API_KEY")
}
func EnvCloudAPISecret() string {
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
return os.Getenv("CLOUDINARY_API_SECRET")
}
func EnvCloudUploadFolder() string {
err := godotenv.Load()
if err != nil {
log.Fatal("Error loading .env file")
}
return os.Getenv("CLOUDINARY_UPLOAD_FOLDER")
}
The snippet above does the following:
- Import the required dependencies.
- Create an
EnvCloudName
,EnvCloudAPIKey
,EnvCloudAPISecret
,EnvCloudUploadFolder
functions that check if the environment variable is correctly loaded and returns the environment variable.
Cloudinary helper function
To facilitate both remote and local upload from our application, we need to navigate to the helper
folder and in this folder, create a media_helper.go
file and add the snippet below:
package helper
import (
"context"
config "gin-cloudinary-api/configs"
"time"
"github.com/cloudinary/cloudinary-go"
"github.com/cloudinary/cloudinary-go/api/uploader"
)
func ImageUploadHelper(input interface{}) (string, error) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
//create cloudinary instance
cld, err := cloudinary.NewFromParams(config.EnvCloudName(), config.EnvCloudAPIKey(), config.EnvCloudAPISecret())
if err != nil {
return "", err
}
//upload file
uploadParam, err := cld.Upload.Upload(ctx, input, uploader.UploadParams{Folder: config.EnvCloudUploadFolder()})
if err != nil {
return "", err
}
return uploadParam.SecureURL, nil
}
The snippet above does the following:
- Import the required dependencies.
- Create an
ImageUploadHelper
function that first takes aninterface
as a parameter and returns the remote URLs or error if there is any. Theinterface
makes our code reusable by accepting both remote URL and a form file. The function also does the following:- Defined a timeout of 10 seconds when connecting to Cloudinary.
- Initialize a new Cloudinary instance by passing in the Cloud Name, API Key, and API Secret as parameters and checking for error if there is any.
- Upload the media using the
Upload
function and specify the folder to store the media using theEnvCloudUploadFolder
function. Get both the upload result and error if there is any. - Returns the media secure URL and
nil
when there is no error.
Setup Models and Response Type
Models
Next, we need a model to represent our application data. To do this, we need to navigate to the models
folder, and in this folder, create a media_model.go
file and add the snippet below:
package models
import "mime/multipart"
type File struct {
File multipart.File `json:"file,omitempty" validate:"required"`
}
type Url struct {
Url string `json:"url,omitempty" validate:"required"`
}
The snippet above does the following:
- Import the required dependency.
- Create a
File
andUrl
struct with the required property for local file upload and remote URL upload.
Response Type
Next, we need to create a reusable struct
to describe our API’s response. To do this, navigate to the dtos
folder and in this folder, create a media_dto.go
file and add the snippet below:
package dtos
type MediaDto struct {
StatusCode int `json:"statusCode"`
Message string `json:"message"`
Data map[string]interface{} `json:"data"`
}
The snippet above creates a MediaDto
struct with StatusCode
, Message
, and Data
property to represent the API response type.
Finally, Creating REST API’s
With that done, we need to create a service to host all the media upload application logics. To do this, navigate to the services
folder and in this folder, create a media_service.go
file and add the snippet below:
package services
import (
"gin-cloudinary-api/helper"
"gin-cloudinary-api/models"
"github.com/go-playground/validator/v10"
)
var (
validate = validator.New()
)
type mediaUpload interface {
FileUpload(file models.File) (string, error)
RemoteUpload(url models.Url) (string, error)
}
type media struct {}
func NewMediaUpload() mediaUpload {
return &media{}
}
func (*media) FileUpload(file models.File) (string, error) {
//validate
err := validate.Struct(file)
if err != nil {
return "", err
}
//upload
uploadUrl, err := helper.ImageUploadHelper(file.File)
if err != nil {
return "", err
}
return uploadUrl, nil
}
func (*media) RemoteUpload(url models.Url) (string, error) {
//validate
err := validate.Struct(url)
if err != nil {
return "", err
}
//upload
uploadUrl, errUrl := helper.ImageUploadHelper(url.Url)
if errUrl != nil {
return "", err
}
return uploadUrl, nil
}
The snippet above does the following:
- Import the required dependencies.
- Create a
validate
variable to validate models using thegithub.com/go-playground/validator/v10
library we installed earlier. - Create a
mediaUpload
interface with methods describing the type of upload we want to do. - Create a
media
struct that will implement themediaUpload
interface. - Create a
NewMediaUpload
constructor function that ties themedia
struct and themediaUpload
interface it implements. - Create the required methods
FileUpload
andRemoteUpload
with amedia
pointer receiver and returns the URL or error if there is any. The required method also validates inputs from the user and uses theImageUploadHelper
function we created earlier to upload media to Cloudinary.
File Upload Endpoint
With the service setup, we can now create a function to upload media from local file storage. To do this, we need to navigate to the controllers
folder, and in this folder, create a media_controller.go
file and add the snippet below:
package controllers
import (
"gin-cloudinary-api/dtos"
"gin-cloudinary-api/models"
"gin-cloudinary-api/services"
"net/http"
"github.com/gin-gonic/gin"
)
func FileUpload() gin.HandlerFunc {
return func(c *gin.Context) {
//upload
formfile, _, err := c.Request.FormFile("file")
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Select a file to upload"},
})
return
}
uploadUrl, err := services.NewMediaUpload().FileUpload(models.File{File: formfile})
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Error uploading file"},
})
return
}
c.JSON(
http.StatusOK,
dtos.MediaDto{
StatusCode: http.StatusOK,
Message: "success",
Data: map[string]interface{}{"data": uploadUrl},
})
}
}
The snippet above does the following:
- Import the required dependencies.
- Create a
FileUpload
function that returns a Gin-gonic handler. Inside the returned handler, we first used theRequest.FormFile
function to retrieve theformFile
object from the request body. We returned the appropriate message and status code using theMediaDto
struct we created earlier. Secondly, we used theNewMediaUpload
constructor to access theFileUpload
service by passing theformFile
as an argument. The service also returns a URL of the uploaded media or an error if there is any. Finally, we returned the correct response if the media upload was successful.
Remote URL Upload Endpoint
To upload an image from a remote URL, we need to modify media_controller.go
as shown below:
package controllers
import (
//all import goes here
)
func FileUpload() gin.HandlerFunc {
return func(c *gin.Context) {
//fileuplod code goes here
}
}
func RemoteUpload() gin.HandlerFunc {
return func(c *gin.Context) {
var url models.Url
//validate the request body
if err := c.BindJSON(&url); err != nil {
c.JSON(
http.StatusBadRequest,
dtos.MediaDto{
StatusCode: http.StatusBadRequest,
Message: "error",
Data: map[string]interface{}{"data": err.Error()},
})
return
}
uploadUrl, err := services.NewMediaUpload().RemoteUpload(url)
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Error uploading file"},
})
return
}
c.JSON(
http.StatusOK,
dtos.MediaDto{
StatusCode: http.StatusOK,
Message: "success",
Data: map[string]interface{}{"data": uploadUrl},
})
}
}
The RemoteUpload
function does the same thing as the FileUpload
function. However, we created url
variable and validate it using the Gin-gonic’s BindJSON
method. We also passed the variable to the RemoteUpload
service as an argument and returned the appropriate response.
Complete media_controller.go
package controllers
import (
"gin-cloudinary-api/dtos"
"gin-cloudinary-api/models"
"gin-cloudinary-api/services"
"net/http"
"github.com/gin-gonic/gin"
)
func FileUpload() gin.HandlerFunc {
return func(c *gin.Context) {
//upload
formFile, _, err := c.Request.FormFile("file")
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Select a file to upload"},
})
return
}
uploadUrl, err := services.NewMediaUpload().FileUpload(models.File{File: formFile})
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Error uploading file"},
})
return
}
c.JSON(
http.StatusOK,
dtos.MediaDto{
StatusCode: http.StatusOK,
Message: "success",
Data: map[string]interface{}{"data": uploadUrl},
})
}
}
func RemoteUpload() gin.HandlerFunc {
return func(c *gin.Context) {
var url models.Url
//validate the request body
if err := c.BindJSON(&url); err != nil {
c.JSON(
http.StatusBadRequest,
dtos.MediaDto{
StatusCode: http.StatusBadRequest,
Message: "error",
Data: map[string]interface{}{"data": err.Error()},
})
return
}
uploadUrl, err := services.NewMediaUpload().RemoteUpload(url)
if err != nil {
c.JSON(
http.StatusInternalServerError,
dtos.MediaDto{
StatusCode: http.StatusInternalServerError,
Message: "error",
Data: map[string]interface{}{"data": "Error uploading file"},
})
return
}
c.JSON(
http.StatusOK,
dtos.MediaDto{
StatusCode: http.StatusOK,
Message: "success",
Data: map[string]interface{}{"data": uploadUrl},
})
}
}
Putting it all together
With that done, we need to create a route for our endpoints to upload media from local file storage and remote URL. To do this, we need to modify main.go
with our controller and specify the relative path as shown below:
package main
import (
"gin-cloudinary-api/controllers" //add this
"github.com/gin-gonic/gin"
)
func main() {
router := gin.Default()
//add
router.POST("/file", controllers.FileUpload())
router.POST("/remote", controllers.RemoteUpload())
router.Run("localhost:6000")
}
With that done, we can test our application by starting the development server by running the command below in our terminal.
go run main.go
After the uploads, we can check the go-cloudinary
folder on Cloudinary to see uploaded media files.
Conclusion
This post discussed how to structure a Gin-gonic application, integrate Cloudinary with Golang and upload media files to Cloudinary using remote URLs and local file storage.
You may find these resources helpful:
Top comments (0)