Encore Go Api

# Encore Go API Endpoints

## Instructions

When creating API endpoints with Encore Go, follow these patterns:

### 1. Basic API Endpoint

Use the `//encore:api` annotation above your function:

```go
package user

import "context"

type GetUserParams struct {
    ID string
}

type User struct {
    ID    string `json:"id"`
    Email string `json:"email"`
    Name  string `json:"name"`
}

//encore:api public method=GET path=/users/:id
func GetUser(ctx context.Context, params *GetUserParams) (*User, error) {
    // Implementation
    return &User{ID: params.ID, Email: "user@example.com", Name: "John"}, nil
}
```

### 2. POST with Request Body

```go
type CreateUserParams struct {
    Email string `json:"email"`
    Name  string `json:"name"`
}

//encore:api public method=POST path=/users
func CreateUser(ctx context.Context, params *CreateUserParams) (*User, error) {
    // Implementation
    return &User{ID: "new-id", Email: params.Email, Name: params.Name}, nil
}
```

## API Annotation Options

| Option | Values | Description |
|--------|--------|-------------|
| `public` | - | Accessible from outside |
| `private` | - | Only callable from other services |
| `auth` | - | Requires authentication |
| `method` | GET, POST, PUT, PATCH, DELETE | HTTP method |
| `path` | string | URL path with `:param` for path params |
| `sensitive` | - | Redacts request/response payloads from traces |

### Examples

```go
//encore:api public method=GET path=/health
//encore:api private method=POST path=/internal/process
//encore:api auth method=GET path=/profile
//encore:api public sensitive method=POST path=/auth/login
```

## Sensitive Data

Mark sensitive fields to redact them from tracing logs:

```go
type LoginParams struct {
    Email    string `json:"email"`
    Password string `json:"password" encore:"sensitive"`
}
```

Or mark the entire endpoint as sensitive in the annotation:

```go
//encore:api public sensitive method=POST path=/auth/login
func Login(ctx context.Context, params *LoginParams) (*TokenResponse, error) {
    // Request and response will be redacted from traces
}
```

## Custom HTTP Status Codes

Return custom HTTP status codes using the `encore:"httpstatus"` tag:

```go
type CreateResponse struct {
    ID     string `json:"id"`
    Status int    `encore:"httpstatus"`
}

//encore:api public method=POST path=/items
func CreateItem(ctx context.Context, params *CreateParams) (*CreateResponse, error) {
    item := createItem(params)
    return &CreateResponse{
        ID:     item.ID,
        Status: 201,  // Returns HTTP 201 Created
    }, nil
}
```

## Request Parameter Sources

### Path Parameters

```go
// Path: /users/:id
type GetUserParams struct {
    ID string  // Automatically mapped from :id
}
```

### Query Parameters

```go
// Path: /users
type ListUsersParams struct {
    Limit  int `query:"limit"`
    Offset int `query:"offset"`
}

//encore:api public method=GET path=/users
func ListUsers(ctx context.Context, params *ListUsersParams) (*ListResponse, error) {
    // params.Limit and params.Offset come from query string
}
```

### Headers

```go
t