OpenParable
Skip to content
← Back to skills

New Endpoint

Development
new-endpoint

New Endpoint is an Agent Skill for development published in the fleetdm/fleet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Scaffold a new Fleet API endpoint with request/response structs, endpoint function, service method, datastore interface, handler registration, and test stubs.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/fleetdm/fleet/blob/HEAD/.claude/skills/new-endpoint/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/new-endpoint, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Scaffold a New Fleet API Endpoint

Create a new API endpoint for: $ARGUMENTS

Process

1. Gather Requirements

  • Resource name and HTTP method (GET/POST/PATCH/DELETE)
  • URL path (e.g., /api/_version_/fleet/resource)
  • Request body fields (if any)
  • Response body fields
  • Which API version (use StartingAtVersion("2022-04") for new endpoints)
  • Does it need a datastore method?

2. Read Reference Patterns

Read server/service/vulnerabilities.go for the canonical request/response/endpoint pattern:

  • Request struct with json tags
  • Response struct with Err error field and Error() method
  • Endpoint function with (ctx, request, svc) signature

Read server/service/handler.go to find where to register the new endpoint.

3. Create Request/Response Structs

type myResourceRequest struct {
    ID   uint   `url:"id"`
    Name string `json:"name"`
}

type myResourceResponse struct {
    Resource *fleet.Resource `json:"resource,omitempty"`
    Err      error           `json:"error,omitempty"`
}

func (r myResourceResponse) Error() error { return r.Err }

4. Create Endpoint Function

func myResourceEndpoint(ctx context.Context, request interface{}, svc fleet.Service) (fleet.Errorer, error) {
    req := request.(*myResourceRequest)
    result, err := svc.MyResource(ctx, req.ID)
    if err != nil {
        return myResourceResponse{Err: err}, nil
    }
    return myResourceResponse{Resource: result}, nil
}

5. Add Service Interface Method

In server/fleet/service.go, add the method to the Service interface.

6. Implement Service Method

In the appropriate server/service/*.go file:

  • Start with svc.authz.Authorize(ctx, &fleet.Entity{}, fleet.ActionRead)
  • Implement business logic
  • Wrap errors with ctxerr.Wrap

7. Add Datastore Interface Method (if needed)

In server/fleet/datastore.go, add the method to the Datastore interface.

8. Register in handler.go

ue.StartingAtVersion("2022-04").GET("/api/_version_/fleet/resource", myResourceEndpoint, myResourceRequest{})

9. Create Test Stubs

  • Unit test with mock datastore in server/service/*_test.go
  • Integration test stub if it touches the database

10. Verify

  • Run go build ./... to check compilation
  • Run go test ./server/service/ to check mocks are satisfied