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
Copy file name to clipboardExpand all lines: docs/api-standards.md
+53-71Lines changed: 53 additions & 71 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,54 +5,49 @@ This document is intended as a collaborative document to agree and define standa
5
5
6
6
## Versioning
7
7
8
-
9
8
* Set the version number in the _info.version_ field.
10
9
* The version should follow [Semantic Versioning](https://semver.org/).
11
-
* A **MAJOR** version change is required when you make incompatible API changes.
12
-
* Removal of an endpoint.
13
-
* Changes to an endpoint URI structure.
14
-
* Modifying a schema object such as a request or response payload object.
15
-
* Removal of a query parameter.
16
-
* Making a non-required parameter required.
17
-
* Modifying a field name.
18
-
* Modifying authorization.
19
-
* Introducing rate-limiting.
20
-
* Removal of a field
21
-
* Addition of a required field in the request object
22
-
* Addition of validation that was not present before
23
-
* A **MINOR**version change is required when an additive change is made to the OpenAPI document.
24
-
* Adding an endpoint.
25
-
* Adding optional query parameters.
26
-
* Adding optional fields to a schema used in a request payload.
27
-
* Adding a response field.
28
-
* A **PATCH**version change is required when a change which fixes broken functionality of the schema.
29
-
* Invalid reference to a schema object
30
-
* Typo in a property such as a tag
31
-
* Errors in the document itself, such as a string that is not closed.
32
-
* A pre-release extension may be added to indicate that the API version is unstable. For example: 2.0.0-alpha1.
10
+
* A **MAJOR** version change is required when you make incompatible API changes.
11
+
* Removal of an endpoint.
12
+
* Changes to an endpoint URI structure.
13
+
* Modifying a schema object such as a request or response payload object.
14
+
* Removal of a query parameter.
15
+
* Making a non-required parameter required.
16
+
* Modifying a field name.
17
+
* Modifying authorization.
18
+
* Introducing rate-limiting.
19
+
* Removal of a field
20
+
* Addition of a required field in the request object
21
+
* Addition of validation that was not present before
22
+
* A **MINOR**version change is required when an additive change is made to the OpenAPI document.
23
+
* Adding an endpoint.
24
+
* Adding optional query parameters.
25
+
* Adding optional fields to a schema used in a request payload.
26
+
* Adding a response field.
27
+
* A **PATCH**version change is required when a change which fixes broken functionality of the schema.
28
+
* Invalid reference to a schema object
29
+
* Typo in a property such as a tag
30
+
* Errors in the document itself, such as a string that is not closed.
31
+
* A pre-release extension may be added to indicate that the API version is unstable. For example: 2.0.0-alpha1.
33
32
* APIs must not expose the minor or patch version in the API URL.
34
-
* For releases which have alpha or beta stability the API **must** append the stability level after the major version using _[Channel-based versioning](https://cloud.google.com/apis/design/versioning)._For example: **v1beta**, **v2alpha**.
33
+
* For releases which have alpha or beta stability the API **must** append the stability level after the major version using _[Channel-based versioning](https://cloud.google.com/apis/design/versioning)._For example: **v1beta**, **v2alpha**.
35
34
* All resource endpoints must include the channel version; `/v1`, `/v2`, `v2beta` etc.
36
-
* /api/srs_mgmt/v1/registries
37
-
* /api/kafka_mgmt/v1/kafkas
38
-
* /api/kafka_mgmt/v2beta/kafkas
35
+
* /api/srs_mgmt/v1/registries
36
+
* /api/kafka_mgmt/v1/kafkas
37
+
* /api/kafka_mgmt/v2beta/kafkas
39
38
* The name of the OpenAPI file should include the version using the following format: \
40
39
“${service_or_api_name}.{yaml | json}”. Some examples:
41
-
* kas-fleet-manager.yaml
42
-
* srs-fleet-manager.json
43
-
* kafka-admin-api.yaml
44
-
40
+
* kas-fleet-manager.yaml
41
+
* srs-fleet-manager.json
42
+
* kafka-admin-api.yaml
45
43
46
44
## Rules
47
45
48
-
49
-
50
46
* Should use OpenAPI v3+
51
47
*`info.license` must be Apache 2.0
52
48
* Every endpoint must have an _operationId_ specified.
53
49
* The `servers` config array is required for control plane APIs and should look as follows: \
54
50
55
-
56
51
```yaml
57
52
servers:
58
53
- url: https://api.openshift.com
@@ -65,23 +60,19 @@ servers:
65
60
description: current domain
66
61
```
67
62
68
-
69
63
* Examples should be provided where possible/appropriate for documentation purposes.
70
64
71
-
72
65
## Naming
73
66
74
-
75
67
### API Paths
76
68
77
-
API endpoints should use _snake_case _for word separation.
69
+
API endpoints should use _snake_case_for word separation.
78
70
79
71
Examples:
80
72
81
73
* /cloud_providers/..
82
74
* /service_accounts/../reset_credentials
83
75
84
-
85
76
### Fields
86
77
87
78
Fields should use _snake_case_ for word separation.
@@ -91,45 +82,41 @@ Examples:
91
82
* cloud_provider_region
92
83
* bootstrap_server_host
93
84
94
-
95
85
### Operations
96
86
97
-
The **operationId **will be used to name methods in the API clients. As such, changes to the names should be treated as breaking changes, and so we should be careful and explicit with our naming of them.
98
-
87
+
The **operationId**will be used to name methods in the API clients. As such, changes to the names should be treated as breaking changes, and so we should be careful and explicit with our naming of them.
99
88
100
-
* **get{Resource}By{Argument}**- get a single Resource
101
-
* getKafkaById
102
-
* getRegistryById
103
-
* getServiceAccountById
104
-
* getTopicByName
89
+
* **get{Resource}By{Argument}**- get a single Resource
90
+
* getKafkaById
91
+
* getRegistryById
92
+
* getServiceAccountById
93
+
* getTopicByName
105
94
* **get{Resources}** - get multiple Resources
106
-
* getRegistries
107
-
* getKafkas
108
-
* getServiceAccounts
109
-
* getTopics
95
+
* getRegistries
96
+
* getKafkas
97
+
* getServiceAccounts
98
+
* getTopics
110
99
* **delete{Resource}?By{Arg}** - Delete a single resource or multiple resources
111
-
* deleteKafkaById
112
-
* deleteTopicByName
113
-
* deleteTopics
114
-
* deleteRegistryById
100
+
* deleteKafkaById
101
+
* deleteTopicByName
102
+
* deleteTopics
103
+
* deleteRegistryById
115
104
* **update{Resource}?By{Argument}** - update a resource or multiple resources
116
-
* updateKafkaById
117
-
* updateKafkaByName
118
-
* updateRegistryById
119
-
* updateTopics
105
+
* updateKafkaById
106
+
* updateKafkaByName
107
+
* updateRegistryById
108
+
* updateTopics
120
109
* **create{Resource}**- create a resource
121
-
* createKafka
122
-
* createRegistry
123
-
* createTopic
124
-
110
+
* createKafka
111
+
* createRegistry
112
+
* createTopic
125
113
126
114
## Security
127
115
128
-
The following security scheme **must** be added to the OpenAPI document.
116
+
The following security scheme **must** be added to the OpenAPI document.
129
117
130
118
Depending on your API this can be applied globally, or per endpoint.
131
119
132
-
133
120
```yaml
134
121
# 1) Define the security scheme type (HTTP bearer)
135
122
components:
@@ -143,29 +130,24 @@ security:
143
130
- bearer: [] # use the same name as above
144
131
```
145
132
146
-
147
-
148
133
## Tags
149
134
150
135
Grouping operations with tags is a good practice and is recommended.
151
136
152
137
If tags are used a root level global “tags” section should be defined matching those used in operations.
153
138
154
-
155
139
## Schemas
156
140
157
141
There are a number of schemas which should be common across all managed service APIs.
0 commit comments