Skip to content

Commit af95f0e

Browse files
grokifyclaude
grokify
and
claude
committed
docs(profiles): add and update profile documentation
- Update default.md with accurate 106 rules, 27 categories - Add comprehensive.md (88 rules, 26 categories) - Add minimal.md (29 rules, 7 categories) - Add microsoft-rest.md (123 rules, 15 categories) - Add microsoft-graph.md (82 rules, 12 categories) - Update mkdocs.yml nav with new profile pages Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent d12f407 commit af95f0e

6 files changed

Lines changed: 716 additions & 75 deletions

File tree

‎docs/profiles/comprehensive.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Comprehensive Profile
2+
3+
The comprehensive profile provides 100% category coverage synthesized from Microsoft REST, Microsoft Graph, Zalando, Google Cloud, Azure, and PayPal guidelines.
4+
5+
## Overview
6+
7+
| Property | Value |
8+
|----------|-------|
9+
| Name | `comprehensive` |
10+
| Version | 1.0.0 |
11+
| Rules | 88 |
12+
| Categories | 26 |
13+
| Focus | Full coverage across all API design areas |
14+
15+
## Philosophy
16+
17+
The comprehensive profile emphasizes:
18+
19+
- **Complete Coverage** - Rules for every API design category
20+
- **Industry Synthesis** - Best practices from major API providers
21+
- **Balanced Strictness** - Mix of error, warn, and info severities
22+
- **Educational** - Learn API design by understanding all categories
23+
24+
## Categories
25+
26+
| Category | Description |
27+
|----------|-------------|
28+
| general | OpenAPI specification requirements |
29+
| naming | Property and parameter naming conventions |
30+
| urls | URL structure and path design |
31+
| http-methods | HTTP method semantics |
32+
| http-status | Status code usage |
33+
| request-response | Request/response patterns |
34+
| headers | HTTP header conventions |
35+
| errors | Error response format |
36+
| pagination | Collection pagination patterns |
37+
| filtering | Query parameter filtering |
38+
| versioning | API versioning strategy |
39+
| compatibility | Breaking change prevention |
40+
| deprecation | Deprecation patterns |
41+
| security | Authentication and authorization |
42+
| documentation | API documentation requirements |
43+
| json | JSON formatting conventions |
44+
| schema | Schema design patterns |
45+
| collections | Collection resource patterns |
46+
| long-running | Async operation patterns |
47+
| conditional | Conditional request handling |
48+
| performance | Performance optimization |
49+
| hypermedia | HATEOAS patterns |
50+
| batch | Batch operation patterns |
51+
| events | Event/webhook patterns |
52+
| actions | Non-CRUD action patterns |
53+
| throttling | Rate limiting patterns |
54+
55+
## Key Rules
56+
57+
### General
58+
59+
| ID | Title | Severity |
60+
|----|-------|----------|
61+
| GEN-001 | Provide OpenAPI specification | error |
62+
| GEN-002 | Provide API info | error |
63+
| GEN-003 | Use semantic versioning | warn |
64+
65+
### Naming
66+
67+
| ID | Title | Severity |
68+
|----|-------|----------|
69+
| NAME-001 | Use camelCase for properties | error |
70+
| NAME-002 | Use plural nouns for collections | error |
71+
72+
### HTTP Methods
73+
74+
| ID | Title | Severity |
75+
|----|-------|----------|
76+
| HTTP-001 | GET must be safe and idempotent | error |
77+
| HTTP-002 | PUT must be idempotent | error |
78+
| HTTP-003 | DELETE must be idempotent | error |
79+
80+
### Errors
81+
82+
| ID | Title | Severity |
83+
|----|-------|----------|
84+
| ERR-001 | Define standard error schema | error |
85+
| ERR-002 | Include error code in responses | warn |
86+
| ERR-003 | Provide actionable error messages | info |
87+
88+
## Usage
89+
90+
```bash
91+
# Lint with comprehensive profile
92+
api-style lint openapi.yaml --profile comprehensive
93+
94+
# Analyze for full compliance
95+
api-style analyze openapi.yaml --profile comprehensive
96+
97+
# List all rules
98+
api-style list-rules --profile comprehensive
99+
100+
# Filter by category
101+
api-style list-rules --profile comprehensive --category errors
102+
```
103+
104+
## When to Use
105+
106+
Use the comprehensive profile when:
107+
108+
- Learning API design principles
109+
- Auditing existing APIs for completeness
110+
- Building internal API style guides
111+
- Need coverage across all design areas
112+
113+
## Comparison to Default
114+
115+
| Aspect | Default | Comprehensive |
116+
|--------|---------|---------------|
117+
| Rules | 106 | 88 |
118+
| Categories | 27 | 26 |
119+
| Focus | SDK-optimized | Full coverage |
120+
| SDK patterns | High priority | Balanced |
121+
| Multi-tenancy | Yes | No |
122+
123+
## Sources
124+
125+
Rules synthesized from:
126+
127+
- Microsoft REST API Guidelines
128+
- Microsoft Graph API Guidelines
129+
- Zalando RESTful API Guidelines
130+
- Google Cloud API Design Guide
131+
- Azure REST API Guidelines
132+
- PayPal API Standards

‎docs/profiles/default.md‎

Lines changed: 104 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,159 @@
11
# Default Profile
22

3-
The default profile provides common REST API best practices applicable to most API projects.
3+
The default profile is an industry-leading API style guide optimized for SDK generation with tools like ogen and openapi-generator. It synthesizes best practices from Stripe, GitHub, Microsoft, and Zalando.
44

55
## Overview
66

77
| Property | Value |
88
|----------|-------|
99
| Name | `default` |
10-
| Version | 1.0.0 |
11-
| Rules | 29 |
12-
| Focus | General REST API design |
10+
| Version | 2.3.0 |
11+
| Rules | 106 |
12+
| Categories | 27 |
13+
| Focus | SDK-optimized API design |
1314

14-
## Categories
15+
## Philosophy
1516

16-
| Category | Rules | Description |
17-
|----------|-------|-------------|
18-
| URI Design | 5 | URL structure and naming |
19-
| HTTP Methods | 5 | Proper HTTP method usage |
20-
| Naming | 4 | Property and parameter naming |
21-
| Errors | 3 | Error response format |
22-
| Responses | 3 | Response structure |
23-
| Documentation | 5 | API documentation |
24-
| Security | 4 | API security |
17+
The default profile emphasizes:
2518

26-
## Key Rules
19+
- **SDK Generation** - Clean generated code with discriminated unions, named schemas, explicit nullability
20+
- **Consistency** - Uniform patterns for operationIds, error handling, pagination
21+
- **Multi-tenancy** - Support for `~` alias patterns for current user/org context
22+
- **Modern Standards** - RFC 9457 Problem Details, OpenAPI 3.1
2723

28-
### URI Design
24+
## Categories
2925

30-
| ID | Title | Severity |
31-
|----|-------|----------|
32-
| URI-001 | Use plural resource names | error |
33-
| URI-002 | Use kebab-case for path segments | error |
34-
| URI-003 | Avoid verbs in paths | warn |
35-
| URI-004 | Use path parameters for resource identifiers | warn |
36-
| URI-005 | Limit path nesting depth | warn |
26+
| Category | Description |
27+
|----------|-------------|
28+
| general | OpenAPI specification requirements |
29+
| naming | Property and parameter naming conventions |
30+
| urls | URL structure and path design |
31+
| http-methods | HTTP method semantics |
32+
| http-status | Status code usage |
33+
| request-response | Request/response patterns |
34+
| headers | HTTP header conventions |
35+
| errors | Error response format (RFC 9457) |
36+
| pagination | Collection pagination patterns |
37+
| filtering | Query parameter filtering |
38+
| versioning | API versioning strategy |
39+
| compatibility | Breaking change prevention |
40+
| deprecation | Deprecation patterns |
41+
| security | Authentication and authorization |
42+
| documentation | API documentation requirements |
43+
| json | JSON formatting conventions |
44+
| schema | Schema design patterns |
45+
| collections | Collection resource patterns |
46+
| long-running | Async operation patterns |
47+
| conditional | Conditional request handling |
48+
| performance | Performance optimization |
49+
| hypermedia | HATEOAS patterns |
50+
| batch | Batch operation patterns |
51+
| events | Event/webhook patterns |
52+
| actions | Non-CRUD action patterns |
53+
| multi-tenancy | Multi-tenant API patterns |
54+
| throttling | Rate limiting patterns |
55+
56+
## Key Rules
3757

38-
### HTTP Methods
58+
### General (PO-001)
3959

4060
| ID | Title | Severity |
4161
|----|-------|----------|
42-
| HTTP-001 | GET requests must not have request body | error |
43-
| HTTP-002 | DELETE requests should not have request body | warn |
44-
| HTTP-003 | POST should return 201 for resource creation | warn |
45-
| HTTP-004 | Use PATCH for partial updates | info |
46-
| HTTP-005 | Operations must have unique operationId | error |
62+
| PO-001 | Provide OpenAPI 3.1 specification | error |
4763

48-
### Naming Conventions
64+
### Naming (PO-002)
4965

5066
| ID | Title | Severity |
5167
|----|-------|----------|
52-
| NAMING-001 | Use camelCase for JSON properties | error |
53-
| NAMING-002 | Use camelCase for query parameters | warn |
54-
| NAMING-003 | Boolean properties should use is/has/can prefix | info |
55-
| NAMING-004 | Use consistent date/time property naming | info |
68+
| PO-002 | Use camelCase for property names | error |
5669

57-
### Error Handling
70+
### URLs (PO-003, PO-004)
5871

5972
| ID | Title | Severity |
6073
|----|-------|----------|
61-
| ERR-001 | Define error responses for operations | warn |
62-
| ERR-002 | Use consistent error response schema | warn |
63-
| ERR-003 | Include 401 response for authenticated endpoints | warn |
74+
| PO-003 | Use kebab-case for URL paths | error |
75+
| PO-004 | Use plural nouns for collection resources | error |
6476

65-
### Responses
77+
### Versioning (PO-005)
6678

6779
| ID | Title | Severity |
6880
|----|-------|----------|
69-
| RESP-001 | Responses must have descriptions | error |
70-
| RESP-002 | Success responses should define content schema | warn |
71-
| RESP-003 | Use consistent pagination format | info |
81+
| PO-005 | Version APIs with URI prefix | error |
7282

73-
### Documentation
83+
### Errors (PO-024)
7484

7585
| ID | Title | Severity |
7686
|----|-------|----------|
77-
| DOC-001 | API must have info description | error |
78-
| DOC-002 | Operations must have summary or description | warn |
79-
| DOC-003 | Parameters must have descriptions | warn |
80-
| DOC-004 | Schema properties should have descriptions | info |
81-
| DOC-005 | Provide examples for schemas | info |
87+
| PO-024 | Use RFC 9457 Problem Details for errors | error |
8288

83-
### Security
89+
### Multi-tenancy (PO-103, PO-104, PO-105)
8490

8591
| ID | Title | Severity |
8692
|----|-------|----------|
87-
| SEC-001 | Define security schemes | warn |
88-
| SEC-002 | Apply security to operations | warn |
89-
| SEC-003 | Avoid API keys in URL | error |
90-
| SEC-004 | Use HTTPS for server URLs | error |
93+
| PO-103 | Support ~ alias for current context | warn |
94+
| PO-104 | Provide tenant-scoped endpoints | warn |
95+
| PO-105 | Document tenant isolation model | info |
9196

9297
## Conformance Levels
9398

94-
### Bronze (Minimum Viable)
99+
### Minimum
95100

96-
Basic structure and methods.
101+
Basic API structure and methods.
97102

98-
- Required categories: `uri-design`, `http-methods`
99-
- Max errors: 0
100-
- Max warnings: 10
103+
- Required rules: Core naming, URL structure, HTTP methods
104+
- Focus: API hygiene
101105

102-
### Silver (Production-Ready)
106+
### Standard
103107

104-
Proper naming and error handling.
108+
Production-ready APIs.
105109

106-
- Includes Bronze requirements
107-
- Required categories: `naming`, `errors`
108-
- Max errors: 0
109-
- Max warnings: 5
110+
- Includes Minimum requirements
111+
- Required rules: Error handling, documentation, security
112+
- Focus: Deployable APIs
110113

111-
### Gold (Exemplary)
114+
### Exemplary
112115

113-
Complete documentation and security.
116+
Best-in-class APIs.
114117

115-
- Includes Silver requirements
116-
- Required categories: `documentation`, `security`
117-
- Max errors: 0
118-
- Max warnings: 0
118+
- Includes Standard requirements
119+
- Required rules: All categories
120+
- Focus: SDK-optimized, fully documented
119121

120122
## Usage
121123

122124
```bash
123125
# Lint with default profile
124-
api-style lint openapi.yaml --profile default
126+
api-style lint openapi.yaml
125127

126-
# Check silver conformance
127-
api-style lint openapi.yaml --profile default --level silver
128+
# Lint with specific conformance level
129+
api-style lint openapi.yaml --level standard
130+
131+
# Combined lint + LLM evaluation
132+
api-style analyze openapi.yaml
133+
134+
# Generate human-readable style guide
135+
api-style generate guide --output docs/
128136

129137
# List all rules
130138
api-style list-rules --profile default
131139
```
132140

141+
## Enforcement Stats
142+
143+
- **Deterministic (Spectral)**: ~34% of rules
144+
- **LLM-evaluable**: 100% of rules have judge criteria
145+
- **SDK-optimized**: Focus on ogen, openapi-generator compatibility
146+
147+
## Comparison to Other Profiles
148+
149+
| Aspect | Default | Azure | Zalando |
150+
|--------|---------|-------|---------|
151+
| Rules | 106 | 23 | 147 |
152+
| Versioning | URI prefix | Date-based | Header |
153+
| Errors | RFC 9457 | Azure format | Problem+JSON |
154+
| Pagination | Cursor-based | OData | Cursor-based |
155+
| SDK Focus | High | Medium | Medium |
156+
133157
## Customization
134158

135159
Extend the default profile with custom rules:
@@ -139,10 +163,15 @@ Extend the default profile with custom rules:
139163
"name": "my-style",
140164
"extends": ["default"],
141165
"rules": [
142-
// Additional rules
166+
{
167+
"id": "CUSTOM-001",
168+
"title": "My custom rule",
169+
"category": "naming",
170+
"severity": "warn"
171+
}
143172
],
144173
"overrides": {
145-
"URI-001": { "severity": "warn" }
174+
"PO-003": { "severity": "warn" }
146175
}
147176
}
148177
```

0 commit comments

Comments
 (0)