You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project uses APIOps Cycles method tooling to design, review, implement, audit, publish, and improve APIs.
4
-
For a brand-new API, start with the method station checks and canvases before filling `specs/openapi/api.yaml`.
3
+
This project is a scaffolded APIOps workspace for creating a new API, producing API design artifacts, or reviewing and improving an existing API.
5
4
6
-
## Structure
5
+
It uses the APIOps Cycles method through the shared `apiops-cycles-method-data` package. The generated project includes CLI commands and local wrapper scripts that help developers, AI assistants, or other tooling move from method guidance into canvases, API contracts, style guidance, and audit work.
7
6
8
-
-`specs/canvases/` = source canvas JSON files
9
-
-`specs/openapi/` = source OpenAPI contracts for later API Design and contract-first work
10
-
-`specs/audit/` = audit reviews and checklists
11
-
-`docs/api/` = rendered SVGs and human-readable outputs
12
-
-`src/` = implementation
7
+
## When to use this project
8
+
9
+
Use this project when you have any of these starting points:
10
+
11
+
- an idea for a new API but not yet a clear scope, contract, or implementation plan
12
+
- an existing API concept and a need to capture the business, domain, and interaction design more clearly
13
+
- an OpenAPI contract that you want to review, improve, or audit with more structured method guidance
14
+
- a need to create reviewable API design artifacts for a team, stakeholders, or governance process
15
+
16
+
You do not need to start with a finished API design. A rough idea, early requirements, or an existing OpenAPI file is enough.
17
+
18
+
## What you get from using it
19
+
20
+
After using this project, you should have:
21
+
22
+
- a structured set of API design artifacts in `specs/`, including canvases, style guidance, audit data, and optionally an OpenAPI contract
23
+
- reviewable documentation and audit outputs in `docs/`
24
+
- APIOps Cycles coverage results that show what is already addressed and where the current design still has gaps
25
+
- a repeatable workflow for improving the API design over time, locally and in CI
26
+
27
+
## What this project does and does not prescribe
28
+
29
+
- The project uses Node.js for the local CLI, helper scripts, linting, and CI workflow.
30
+
- It does not require your API implementation itself to use Node.js.
31
+
- You can implement the actual API in any language or platform, such as Java, C#, Go, Python, Node.js, or a gateway-based platform.
32
+
- The main requirement is that your API design artifacts, especially the OpenAPI contract and audit inputs, are kept in this project structure.
33
+
34
+
## What else you may need
35
+
36
+
This project helps you design, review, and govern an API, but it is not the full runtime or deployment solution.
37
+
38
+
To complete and publish an API, you will usually still need:
39
+
40
+
- an actual implementation or backend service
41
+
- deployment and hosting infrastructure
42
+
- an API gateway or publishing channel if your organization uses one
43
+
- developer documentation publishing and access management as needed
44
+
- organization-specific delivery, security, and operational tooling
45
+
46
+
In other words, this project gives you the design-time and review-time workspace. You may still need separate tools or platforms for implementation, deployment, publishing, and runtime operations.
13
47
14
48
## Install
15
49
16
50
```bash
17
-
npm install
51
+
npm create apiops@latest
18
52
```
19
53
54
+
## What this project contains
55
+
56
+
-`specs/canvases/` for canvas JSON source files used to explore business, domain, and API design decisions
57
+
-`specs/openapi/api.yaml` for the local project-owned API contract when the work is ready to move into OpenAPI design
58
+
-`specs/style/` for optional project-local style guide overrides when you need to replace the canonical default
59
+
-`specs/audit/` for generated audit outputs and optional local checklist overrides
60
+
-`docs/` for rendered or review-oriented artifacts
61
+
-`scripts/` for project-local helper commands that wrap shared package functionality
62
+
63
+
Treat `specs/` as the source of truth and `docs/` as generated or review material.
64
+
20
65
## Useful commands
21
66
22
67
```bash
@@ -26,18 +71,90 @@ npm run method:canvases:new-api
26
71
npm run method -- resources --station api-design --style "__API_STYLE__"
27
72
npm run method:stations
28
73
npm run method:resource:audit
74
+
npm run lint:openapi
75
+
npm run validate:openapi
76
+
npm run audit:design
77
+
npm run audit:design:full-crud
29
78
```
30
79
31
-
## Notes
32
-
33
-
- Start with `npm run method:start`; in an interactive terminal it asks one criterion at a time and recommends the station to begin from.
34
-
-`npm run method:resources:strategy` now walks the station steps one by one, and lets you inspect each related resource or canvas before continuing.
35
-
- For canvas steps, the CLI can show the related canvas structure, save starter JSON, guide section-by-section note entry, or give you a CanvasCreator URL for browser-based editing and export.
36
-
- If you want to build your own helper app or automation, you can also import the shared method logic from `apiops-cycles-method-data/method-engine`.
37
-
- Continue with the generated strategy canvases before moving into API contract work.
38
-
- Treat `specs/openapi/api.yaml` as a later artifact, not the first design step for a new API.
39
-
- Keep source artifacts version controlled
40
-
- Treat `specs/` as source of truth
41
-
- Treat `docs/` as rendered review material
80
+
## How to use it
81
+
82
+
- Use `npm run method:start` to find the right station to begin from. In an interactive terminal it checks criteria one by one and recommends where to start.
83
+
- Use the `method:resources:*` commands or `npm run method -- resources --station ...` to walk the method resources for a station and inspect related canvases or snippets.
84
+
- Use `npm run method:canvases:new-api` to generate starter canvas JSON files for a new API initiative.
85
+
- Use the generated canvas files to capture scope, business needs, domain understanding, and interface options before going too early into contract details.
86
+
- Use `specs/openapi/api.yaml` when you are ready to produce or review API contract details.
87
+
- The starter `specs/openapi/api.yaml` is copied during scaffolding from the canonical package example and then becomes project-specific.
88
+
- Use the canonical style and audit JSON assets from the package when reviewing design consistency, governance, and quality expectations.
89
+
- Add local override files under `specs/style/` or `specs/audit/` only when this project needs to customize those defaults.
90
+
91
+
## Linting and audit coverage
92
+
93
+
- Use `npm run lint:openapi` to lint the current OpenAPI contract with the read-only Spectral ruleset.
94
+
- Use `npm run lint:openapi:full-crud` when you want the stricter full CRUD ruleset.
95
+
- Use `npm run validate:openapi` to run both lint profiles in sequence.
96
+
- Use `npm run audit:design` to generate the APIOps Cycles coverage report for the `read-only` profile.
97
+
- Use `npm run audit:design:full-crud` to generate the same report for the `full-crud` profile.
98
+
99
+
The Spectral configuration in this project is split into a default config file and explicit profile rulesets:
100
+
101
+
-`.spectral.yaml` is the default Spectral entry point and extends `./spectral/read-only.yaml`
102
+
-`spectral/base.yaml` contains the shared OpenAPI rules used by all profiles
103
+
-`spectral/read-only.yaml` adds rules for read-only APIs, such as blocking `POST`, `PUT`, `PATCH`, and `DELETE`
104
+
-`spectral/full-crud.yaml` uses the shared base rules without the read-only restrictions
105
+
106
+
In practice:
107
+
108
+
- the npm lint scripts call the profile files in `spectral/` directly
109
+
- the GitHub Actions workflow uses those same npm scripts
110
+
-`scripts/run-design-audit.js` also selects the matching Spectral ruleset directly when generating coverage reports
111
+
-`.spectral.yaml` is still useful as the default config for editor integrations or manual commands like `spectral lint specs/openapi/api.yaml`
112
+
113
+
The audit command writes multiple outputs so the same result can be used by developers, docs, and CI:
114
+
115
+
-`specs/audit/design-audit.<profile>.json` as the canonical machine-readable result
116
+
-`specs/audit/design-audit.<profile>.md` as the local Markdown report
117
+
-`docs/api/audit/design-audit.<profile>.md` as the docs-side Markdown copy
118
+
-`docs/api/audit/design-audit.<profile>.html` as the rendered APIOps Cycles Coverage page
119
+
-`reports/junit/design-audit.<profile>.xml` as the CI-friendly JUnit result
120
+
121
+
## GitHub Actions
122
+
123
+
This template includes `.github/workflows/openapi-lint.yml`, which runs on pushes, pull requests, and manual dispatch.
124
+
125
+
The workflow:
126
+
127
+
- installs dependencies with `npm ci`
128
+
- runs Spectral linting for the selected audit profile
129
+
- generates the audit coverage artifacts
130
+
- publishes the JUnit XML result as a GitHub check named `APIOps Cycles coverage (<profile>)`
131
+
132
+
This makes the generated project useful both for local design work and for automated API review in CI.
133
+
134
+
## Using skills with AI assistants
135
+
136
+
This template also supports AI-assisted work through the skill instructions in `AGENTS.md`.
137
+
138
+
The main skills available in a generated project are:
139
+
140
+
-`new-api-guide` for moving through the APIOps Cycles method from strategy to design and review
141
+
-`canvas-import-json-authoring` for creating or validating CanvasCreator import JSON
142
+
-`export-cli-usage-patterns` for exporting canvas artifacts and troubleshooting export flows
143
+
144
+
In practice, this means an AI assistant can use the same project as a developer:
145
+
146
+
- start from `npm run method:start` to identify the right station
147
+
- inspect station resources and related snippets or canvases
148
+
- generate or fill canvas JSON in `specs/canvases/`
149
+
- review or improve `specs/openapi/api.yaml`
150
+
- run linting and audit coverage checks
151
+
152
+
The skill guidance is meant to keep AI work aligned with the project structure: prefer the shared method engine and local wrapper scripts, keep editable source artifacts in `specs/`, and treat `docs/` as rendered or review-oriented output.
153
+
154
+
## Working style
155
+
156
+
- Continue with the canvases before moving into detailed API contract work for a brand new API.
157
+
- This project can also be used for an existing API by reviewing the current design against the canvases, style guide, and audit checklist.
158
+
- If you are building your own helper app, agent, or automation, you can also import the shared method logic from `apiops-cycles-method-data/method-engine`.
0 commit comments