Quick Start

Build your first Goose application in under 5 minutes.

Create Your First API

Step 1: Create the Application

goose app --name=myapi --template=api

This creates a new API application with the following structure:

myapi/
├── .env
├── go.mod
├── main.go
└── app/
    ├── app.module.go
    ├── app.controller.go
    ├── app.service.go
    ├── app.routes.go
    └── app.dtos.go

Step 2: Install Dependencies

cd myapi
go mod tidy

Step 3: Run the Application

go run main.go

Your API is now running at http://localhost:8080!

Step 4: Test the API

Open a new terminal and test your API:

curl http://localhost:8080/

Response:

{
  "message": "Welcome to Goose API!"
}

Understanding the Generated Code

main.go

package main

import (
    "myapi/app"
    "github.com/awesome-goose/goose"
    "github.com/awesome-goose/goose/platforms/api"
)

func main() {
    // Create the API platform with configuration
    platform := api.NewPlatform(
        api.WithHost("localhost"),
        api.WithPort(8080),
    )

    // Create the application module
    module := &app.AppModule{}

    // Start the application
    stop, err := goose.Start(goose.API(platform, module, nil))
    if err != nil {
        panic(err)
    }
    defer stop()
}

app/app.module.go

package app

import "github.com/awesome-goose/goose/types"

type AppModule struct{}

// Declarations returns components this module provides
func (m *AppModule) Declarations() []any {
    return []any{
        &AppController{},
        &AppService{},
    }
}

// Exports returns components available to other modules
func (m *AppModule) Exports() []any {
    return []any{}
}

// Imports returns modules this module depends on
func (m *AppModule) Imports() []types.Module {
    return []types.Module{}
}

app/app.controller.go

package app

import "github.com/awesome-goose/goose/types"

type AppController struct {
    service *AppService `inject:""`
}

func (c *AppController) Index(ctx types.Context) any {
    return c.service.GetWelcomeMessage()
}

app/app.routes.go

package app

import "github.com/awesome-goose/goose/types"

func (c *AppController) Routes() types.Routes {
    return types.Routes{
        {Method: "GET", Path: "/", Handler: c.Index},
    }
}

Adding a New Endpoint

Let's add a /hello/:name endpoint:

1. Add the Handler Method

In app/app.controller.go:

func (c *AppController) Hello(ctx types.Context) any {
    name := ctx.Param("name")
    return map[string]string{
        "message": "Hello, " + name + "!",
    }
}

2. Register the Route

In app/app.routes.go:

func (c *AppController) Routes() types.Routes {
    return types.Routes{
        {Method: "GET", Path: "/", Handler: c.Index},
        {Method: "GET", Path: "/hello/:name", Handler: c.Hello},
    }
}

3. Test It

curl http://localhost:8080/hello/World

Response:

{
  "message": "Hello, World!"
}

Creating Different Application Types

Web Application

goose app --name=myweb --template=web

CLI Application

goose app --name=mycli --template=cli

Multi-Platform Application

goose app --name=mymulti --template=multi

This creates an application that combines API, Web, and CLI platforms.

Adding Modules

Generate a new module in your application:

# Navigate to your project
cd myapi

# Generate a plain module
goose g module --name=users --type=plain

# Or generate a resource module with CRUD operations
goose g module --name=posts --type=resource

Next Steps

Now that you have a running application: