Skip to content

Commit 53ba63d

Browse files
yelizhenden-mdbyelizhenden-mdb
committed
ipa docs fix
1 parent a562bab commit 53ba63d

File tree

1 file changed

+57
-67
lines changed

1 file changed

+57
-67
lines changed

‎tools/spectral/ipa/rulesets/README.md‎

Lines changed: 57 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -14,198 +14,188 @@ Rule is based on [http://go/ipa/IPA-5](http://go/ipa/IPA-5).
1414

1515
#### xgen-IPA-005-exception-extension-format
1616

17-
![error](https://img.shields.io/badge/error-red)
17+
![error](https://img.shields.io/badge/error-red)
1818
IPA exception extensions must follow the correct format. http://go/ipa/5
1919

2020
##### Implementation details
21-
2221
Rule checks for the following conditions:
22+
- Exception rule names must start with 'xgen-IPA-' prefix
23+
- Each exception must include a non-empty reason as a string
24+
- This rule itself does not allow exceptions
25+
2326

24-
- Exception rule names must start with 'xgen-IPA-' prefix
25-
- Each exception must include a non-empty reason as a string
26-
- This rule itself does not allow exceptions
2727

2828
### IPA-102
2929

3030
Rule is based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102).
3131

3232
#### xgen-IPA-102-path-alternate-resource-name-path-param
3333

34-
![error](https://img.shields.io/badge/error-red)
34+
![error](https://img.shields.io/badge/error-red)
3535
Paths should alternate between resource names and path params. http://go/ipa/102
36-
3736
#### xgen-IPA-102-collection-identifier-camelCase
3837

39-
![warn](https://img.shields.io/badge/warning-yellow)
38+
![warn](https://img.shields.io/badge/warning-yellow)
4039
Collection identifiers must be in camelCase.
4140

42-
##### Implementation details
41+
##### Implementation details
42+
Rule checks for the following conditions:
4343

44-
Rule checks for the following conditions:
45-
46-
- All path segments that are not path parameters
47-
- Only the resource identifier part before any colon in custom method paths (e.g., `resource` in `/resource:customMethod`)
48-
- Path parameters should also follow camelCase naming
49-
- Certain values can be exempted via the ignoredValues configuration that can be supplied as `ignoredValues`
50-
argument to the rule
51-
- Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
52-
- Double slashes (//) are not allowed in paths
44+
- All path segments that are not path parameters
45+
- Only the resource identifier part before any colon in custom method paths (e.g., `resource` in `/resource:customMethod`)
46+
- Path parameters should also follow camelCase naming
47+
- Certain values can be exempted via the ignoredValues configuration that can be supplied as `ignoredValues`
48+
argument to the rule
49+
- Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
50+
- Double slashes (//) are not allowed in paths
5351

5452
#### xgen-IPA-102-collection-identifier-pattern
5553

56-
![warn](https://img.shields.io/badge/warning-yellow)
54+
![warn](https://img.shields.io/badge/warning-yellow)
5755
Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers. http://go/ipa/102
5856

57+
5958
### IPA-104
6059

6160
Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104).
6261

6362
#### xgen-IPA-104-resource-has-GET
6463

65-
![warn](https://img.shields.io/badge/warning-yellow)
64+
![warn](https://img.shields.io/badge/warning-yellow)
6665
APIs must provide a Get method for resources. http://go/ipa/104
67-
6866
#### xgen-IPA-104-get-method-returns-single-resource
6967

70-
![warn](https://img.shields.io/badge/warning-yellow)
68+
![warn](https://img.shields.io/badge/warning-yellow)
7169
The purpose of the Get method is to return data from a single resource. http://go/ipa/104
72-
7370
#### xgen-IPA-104-get-method-response-code-is-200
7471

75-
![warn](https://img.shields.io/badge/warning-yellow)
72+
![warn](https://img.shields.io/badge/warning-yellow)
7673
The Get method must return a 200 OK response. http://go/ipa/104
77-
7874
#### xgen-IPA-104-get-method-returns-response-suffixed-object
7975

80-
![warn](https://img.shields.io/badge/warning-yellow)
76+
![warn](https://img.shields.io/badge/warning-yellow)
8177
The Get method of a resource should return a "Response" suffixed object. http://go/ipa/104
82-
8378
#### xgen-IPA-104-get-method-response-has-no-input-fields
8479

85-
![warn](https://img.shields.io/badge/warning-yellow)
80+
![warn](https://img.shields.io/badge/warning-yellow)
8681
The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields). http://go/ipa/104
87-
8882
#### xgen-IPA-104-get-method-no-request-body
8983

90-
![warn](https://img.shields.io/badge/warning-yellow)
84+
![warn](https://img.shields.io/badge/warning-yellow)
9185
The Get method request must not include a body. http://go/ipa/104
9286

87+
9388
### IPA-105
9489

9590
Rule is based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105).
9691

9792
#### xgen-IPA-105-list-method-response-code-is-200
9893

99-
![warn](https://img.shields.io/badge/warning-yellow)
94+
![warn](https://img.shields.io/badge/warning-yellow)
10095
The List method must return a 200 OK response. http://go/ipa/105
101-
10296
#### xgen-IPA-105-list-method-no-request-body
10397

104-
![warn](https://img.shields.io/badge/warning-yellow)
98+
![warn](https://img.shields.io/badge/warning-yellow)
10599
The List method request must not include a body. http://go/ipa/105
106-
107100
#### xgen-IPA-105-resource-has-list
108101

109-
![warn](https://img.shields.io/badge/warning-yellow)
102+
![warn](https://img.shields.io/badge/warning-yellow)
110103
APIs must provide a List method for resources. http://go/ipa/105
111-
112104
#### xgen-IPA-105-list-method-response-is-get-method-response
113105

114-
![warn](https://img.shields.io/badge/warning-yellow)
106+
![warn](https://img.shields.io/badge/warning-yellow)
115107
The response body of the List method should consist of the same resource object returned by the Get method. http://go/ipa/105
116-
117108
##### Implementation details
118-
119109
Validation checks that the List method response contains items property with reference to the same schema as the Get method response.
120110

121-
- Validation applies to List methods for resource collections only
122-
- Validation applies to json response content only
123-
- Validation ignores responses without schema and non-paginated responses
124-
- A response is considered paginated if it contains an array property named `results`
125-
- Validation ignores resources without a Get method
126-
- Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
111+
- Validation applies to List methods for resource collections only
112+
- Validation applies to json response content only
113+
- Validation ignores responses without schema and non-paginated responses
114+
- A response is considered paginated if it contains an array property named `results`
115+
- Validation ignores resources without a Get method
116+
- Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
117+
127118

128119
### IPA-106
129120

130121
Rule is based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106).
131122

132123
#### xgen-IPA-106-create-method-request-body-is-request-suffixed-object
133124

134-
![warn](https://img.shields.io/badge/warning-yellow)
125+
![warn](https://img.shields.io/badge/warning-yellow)
135126
The Create method request should be a Request suffixed object. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
136-
137127
#### xgen-IPA-106-create-method-should-not-have-query-parameters
138128

139-
![warn](https://img.shields.io/badge/warning-yellow)
129+
![warn](https://img.shields.io/badge/warning-yellow)
140130
Create operations should not use query parameters. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
141-
142131
#### xgen-IPA-106-create-method-request-body-is-get-method-response
143132

144-
![warn](https://img.shields.io/badge/warning-yellow)
145-
Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly:true properties of Get method response will be ignored. writeOnly:true properties of Create method request will be ignored. This rule applies only to POST requests targeting resource collection URIs.
146-
133+
![warn](https://img.shields.io/badge/warning-yellow)
134+
Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly:true properties of Get method response will be ignored. writeOnly:true properties of Create method request will be ignored. This rule applies only to POST requests targeting resource collection URIs.
147135
#### xgen-IPA-106-create-method-request-has-no-readonly-fields
148136

149-
![warn](https://img.shields.io/badge/warning-yellow)
137+
![warn](https://img.shields.io/badge/warning-yellow)
150138
Create method Request object must not include fields with readOnly:true. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
151-
152139
#### xgen-IPA-106-create-method-response-code-is-201
153140

154-
![warn](https://img.shields.io/badge/warning-yellow)
141+
![warn](https://img.shields.io/badge/warning-yellow)
155142
Create methods must return a 201 Created response code. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
156143

144+
157145
### IPA-108
158146

159147
Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108).
160148

161149
#### xgen-IPA-108-delete-response-should-be-empty
162150

163-
![warn](https://img.shields.io/badge/warning-yellow)
151+
![warn](https://img.shields.io/badge/warning-yellow)
164152
Delete method response should not have schema reference to object. http://go/ipa/108
165-
166153
#### xgen-IPA-108-delete-method-return-204-response
167154

168-
![warn](https://img.shields.io/badge/warning-yellow)
155+
![warn](https://img.shields.io/badge/warning-yellow)
169156
DELETE method must return 204 No Content. http://go/ipa/108
170-
171157
#### xgen-IPA-108-delete-include-404-response
172158

173-
![warn](https://img.shields.io/badge/warning-yellow)
159+
![warn](https://img.shields.io/badge/warning-yellow)
174160
DELETE method must include 404 response and return it when resource not found. http://go/ipa/108
175-
176161
#### xgen-IPA-108-delete-request-no-body
177162

178-
![warn](https://img.shields.io/badge/warning-yellow)
163+
![warn](https://img.shields.io/badge/warning-yellow)
179164
DELETE method must not have request body. http://go/ipa/108
180165

166+
181167
### IPA-109
182168

183169
Rule is based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109).
184170

185171
#### xgen-IPA-109-custom-method-must-be-GET-or-POST
186172

187-
![error](https://img.shields.io/badge/error-red)
173+
![error](https://img.shields.io/badge/error-red)
188174
The HTTP method for custom methods must be GET or POST. http://go/ipa/109
189-
190175
#### xgen-IPA-109-custom-method-must-use-camel-case
191176

192-
![error](https://img.shields.io/badge/error-red)
177+
![error](https://img.shields.io/badge/error-red)
193178
The custom method must use camelCase format. http://go/ipa/109
194179

180+
195181
### IPA-113
196182

197183
Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113).
198184

199185
#### xgen-IPA-113-singleton-must-not-have-id
200186

201-
![warn](https://img.shields.io/badge/warning-yellow)
187+
![warn](https://img.shields.io/badge/warning-yellow)
202188
Singleton resources must not have a user-provided or system-generated ID. http://go/ipa/113
203189

190+
204191
### IPA-123
205192

206193
Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123).
207194

208195
#### xgen-IPA-123-enum-values-must-be-upper-snake-case
209196

210-
![error](https://img.shields.io/badge/error-red)
197+
![error](https://img.shields.io/badge/error-red)
211198
Enum values must be UPPER_SNAKE_CASE. http://go/ipa/123
199+
200+
201+

0 commit comments

Comments
 (0)