Quick Start Guide

Prerequisite

  • Install or update Go.

    To check the version use the following command go version.

  • Prior familiarity with Golang syntax is essential. Golang Tour is highly recommended as it has an excellent guided tour.

Write your first GoFr API

Let's start by initializing the go module by using the following command.

go mod init github.com/example

To know more about go modules refer here

Add gofr package to the project using the following command

go get gofr.dev

Now add the following code to main.go file

package main

import "gofr.dev/pkg/gofr"

func main() {
    // initialise gofr object
    app := gofr.New()

    // register route greet
    app.GET("/greet", func(ctx *gofr.Context) (interface{}, error) {

        return "Hello World!", nil
    })

    // Runs the server, it will listen on the default port 8000.
    // it can be over-ridden through configs
   app.Run()
}

Before running the server run the following command to go needs to download and sync the required modules.

go mod tidy

To run the server, use the command

go run main.go

This would start the server at 8000 port, you can access http://localhost:8000/greet from your browser, you would be able to see the output as following with Status Code 200 as per REST Standard

{ "data": "Hello World!" }

Understanding the example

The hello-world server involves three essential steps:

  1. Creating GoFr Server:

    When gofr.New() is called, it initializes the framework and handles various setup tasks like initialising logger, metrics, datasources etc based on the configs.

    This single line is a standard part of all gofr-based servers.

  2. Attaching a Handler to a Path:

    In this step, we instruct the server to associate an HTTP request with a specific handler function. This is achieved through app.GET("/greet", HandlerFunction), where GET /hello maps to HandlerFunction. Likewise, app.POST("/todo", ToDoCreationHandler) links a POST request to the /todo endpoint with ToDoCreationHandler.

    Good To Know

    In Go, functions are first-class citizens, allowing easy handler definition and reference. Handler functions should follow the func(ctx *gofr.Context) (interface{}, error) signature. They take a context as input, returning two values: the response data and an error (set to nil on success).

    In GoFr ctx *gofr.Context serves as a wrapper for requests, responses, and dependencies, providing various functionalities.

    For more details about context, refer here.

  3. Starting the server

    When app.Run() is called, it configures ,initiates and runs the HTTP server, middlewares based on provided configs. It manages essential features such as routes for health checks, swagger UI etc. It starts the server on the default port 8000.