From a5a09e615d79b856eda6eaaf622737e6c94abf3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Sat, 15 Aug 2026 23:11:20 -0700 Subject: [PATCH] docs: point the SDK rules at the capability The rules governing pkg/sdk lived in two documents addressed to people working inside osapi, while binding osapi-orchestrator, which is built on the SDK and cannot see them. CLAUDE.md drops the naming block the capability now states. guidelines.md keeps its worked examples and points at the specification for the rules they illustrate. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 39 ++++------------------------- docs/docs/sidebar/sdk/guidelines.md | 15 +++++++++-- 2 files changed, 18 insertions(+), 36 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fee48ba3c..d463eda75 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -710,41 +710,12 @@ with context. under the matching category header. The dropdown is grouped the same way as the sidebar. -#### SDK method naming (MANDATORY) +#### SDK method naming -Method names MUST be clean verbs — NEVER repeat the service name. The service -struct already provides the namespace. Stuttering like -`SysctlService.SysctlGet()` is wrong — use `SysctlService.Get()`. - -Standard verbs: - -| Verb | HTTP | Description | -| -------- | ---- | -------------------------------- | -| `List` | GET | List collection | -| `Get` | GET | Get single resource / read state | -| `Create` | POST | Create new resource | -| `Update` | PUT | Update existing resource | -| `Delete` | DEL | Remove resource | - -Rare exceptions for action operations (no persistent resource): - -- `Ping.Do()` — one-shot action -- `Command.Exec()`, `Command.Shell()` — execute commands - -Examples: - -```go -// GOOD — clean verbs, no stuttering -client.Sysctl.Get(ctx, host, key) -client.Cron.Create(ctx, host, opts) -client.Hostname.Update(ctx, host, name) -client.NTP.Delete(ctx, host) -client.Timezone.Get(ctx, host) - -// BAD — stuttering, repeats service name -client.Sysctl.SysctlGet(ctx, host, key) -client.NTP.NtpCreate(ctx, host, opts) -``` +Method naming, type exposure, result-field tags, and error handling are +specified in the `sdk-standards` capability in +[osapi-io/specs](https://github.com/osapi-io/specs). When a convention here and +the specification disagree, the specification wins. #### SDK example conventions diff --git a/docs/docs/sidebar/sdk/guidelines.md b/docs/docs/sidebar/sdk/guidelines.md index 143487ecf..31ffb0b36 100644 --- a/docs/docs/sidebar/sdk/guidelines.md +++ b/docs/docs/sidebar/sdk/guidelines.md @@ -4,8 +4,19 @@ sidebar_position: 1 # SDK Development Guidelines -Rules for developing the OSAPI Go SDK (`pkg/sdk/`). These apply to the client -library and any new SDK packages. +How to develop the OSAPI Go SDK (`pkg/sdk/`), with worked examples. Applies to +the client library and any new SDK packages. + +:::note + +The rules this page illustrates — method naming, keeping generated types out of +public signatures, JSON tags on result fields, and error handling — are +specified in the `sdk-standards` capability in +[osapi-io/specs](https://github.com/osapi-io/specs). They bind +`osapi-orchestrator` as well, which is built on this SDK. Where this page and +the specification disagree, the specification wins. + +::: ## Package Structure