Build a REST API

This guide shows a practical shape for a REST backend.

Controller

type Projects struct {
  sdk.Controller `path:"/projects"`

  Store project.Store `inject:""`

  Routes struct {
    Create sdk.POST `path:"/"`
    List   sdk.GET  `path:"/"`
    Get    sdk.GET  `path:"/:projectId"`
    Update sdk.PUT  `path:"/:projectId"`
    Delete sdk.DELETE `path:"/:projectId"`
  }
}

Request Models

type CreateProjectRequest struct {
  Name string `json:"name" validate:"required,min=2,max=80"`
}

type ProjectIDRequest struct {
  ProjectID project.ID `param:"projectId" validate:"required"`
}

Handlers

Keep handlers short:

func (p *Projects) Create(ctx sdk.Ctx, req CreateProjectRequest) (ProjectDTO, error) {
  created, err := p.Store.Create(ctx.Context(), req.Name)
  if err != nil {
    return ProjectDTO{}, ctx.Errors().Wrap(err, "creating project")
  }

  ctx.Response().Status(http.StatusCreated)
  ctx.Response().Header("Location", "/projects/"+created.ID.String())
  return projectDTO(created), nil
}

Tests

Use the generated manifest and HTTP testbeds for route-level tests. Use regular Go tests for domain behavior.