forked from italia/api-oas-checker
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paths.yml
132 lines (113 loc) · 3.28 KB
/
paths.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
rules:
paths-status:
description: |-
You must define a `/status` path that can be used to health-check the API.
Using this path avoids the arbitrary usage of a server URL for health-check
scope.
The `/status` endpoint should return a `application/problem+json` response
containing a successful status code if the service is working correctly.
The service provider is free to define the implementation logic for this path.
message: >-
The "/status" path used to health-check the API must be defined. {{error}}
severity: error
recommended: true
given: $.paths
then:
function: schema
functionOptions:
schema:
oneOf:
- type: object
required:
- "/status"
properties:
"/status":
type: object
- type: object
additionalProperties: false
paths-status-return-problem:
description: |-
"/status" must return a Problem object.
message: |-
{{error}}
severity: error
recommended: true
given: >-
$.paths.'/status'.get.responses.200.content.*~
then:
function: enumeration
functionOptions:
values:
- application/problem+xml
- application/problem+json
paths-status-problem-schema:
description: |-
"/status" schema is not a Problem object.
message: |-
{{error}} {{path}}
severity: warn
recommended: true
given: >-
$.paths.'/status'.get.responses.200.content.[[schema]]
then:
- function: truthy
field: 'properties.status'
- function: truthy
field: 'properties.title'
- function: truthy
field: 'properties.detail'
paths-http-method:
description: |-
When you design a REST API, you don't usually need to mention terms like
`get`, `delete` and so on in your `paths`, because this information is
conveyed by the HTTP method.
Instead of using
```
POST /books/1234/delete HTTP/1.1
Host: api.example
```
You can simply call
```
DELETE /books/1234 HTTP/1.1
Host: api.example
```
Similarly you don't need verbs like `list` or `create` because
the HTTP Semantics RFC7231 supports this kind of actions natively
with proper methods and status code.
Instead of
```
POST /create/user HTTP/1.1
Host: api.example
Content-Type: application/json
{"given_name": "Mario"}
```
You can use
```
POST /create/user HTTP/1.1
Host: api.example
Content-Type: application/json
{"given_name": "Mario"}
```
returning a proper response
```
HTTP/1.1 201 Created
Location: /users/1234
```
This simplifies securing your API as you know beforehand the kind of action
which is going to be performed.
message: >-
API "path" contains a name of an http method. {{error}}
severity: hint
recommended: true
given:
- >-
$.paths[?(@property && @property.match(
"/(get|post|put|delete|patch)[\/A-Z_\-]?"
))]~
- >-
$.paths[?(@property && @property.match(
"/(create|remove|list)[\/A-Z_\-]?"
))]~
then:
field: "@key"
function: undefined