@vindentech/api-client 1.0.0 → 1.1.0-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -163,10 +163,31 @@ The SDK is bearer-token agnostic — *how* you get the token is up to the consum
|
|
|
163
163
|
|
|
164
164
|
## Versioning
|
|
165
165
|
|
|
166
|
-
This SDK is regenerated from the Core API's OpenAPI spec.
|
|
166
|
+
This SDK is regenerated from the Core API's OpenAPI spec. A version says what upgrading does
|
|
167
|
+
to your build: a breaking change is one that can stop code written against the previous
|
|
168
|
+
version from compiling.
|
|
167
169
|
|
|
168
170
|
| Bump | When |
|
|
169
171
|
|---|---|
|
|
170
|
-
| **
|
|
171
|
-
| **Minor** (`
|
|
172
|
-
| **
|
|
172
|
+
| **Major** (`1.4.0 → 2.0.0`) | Any breaking change. Removed or renamed endpoints, fields and types, a changed field type, a field that became nullable, a newly-required request field or param, and the changes listed below. |
|
|
173
|
+
| **Minor** (`1.4.0 → 1.5.0`) | New endpoints, new response fields, new optional request fields and params. Nothing breaking. |
|
|
174
|
+
| **Patch** (`1.4.0 → 1.4.1`) | No change to the API: a generator fix, the README, build config. |
|
|
175
|
+
|
|
176
|
+
Some breaking changes are easy to miss:
|
|
177
|
+
|
|
178
|
+
| Change | What stops compiling |
|
|
179
|
+
|---|---|
|
|
180
|
+
| A response status documented on an existing route, error or success | The operation's `…Response` type gains a member, so `res.data` has to be narrowed on `res.status` before use. A non-2xx response still throws `VindenApiError`; only the type changed. |
|
|
181
|
+
| A value added to a response enum | An exhaustive `switch` over it. |
|
|
182
|
+
| A value removed from a response enum | A comparison with that value. |
|
|
183
|
+
| A field or endpoint removed after it was deprecated | Whatever still uses it. Deprecating something is not breaking; removing it is. |
|
|
184
|
+
| An operation renamed | Calls to it: the function is named after the operation's id. |
|
|
185
|
+
| A request or response type renamed or removed | Imports of it: every DTO is exported. |
|
|
186
|
+
|
|
187
|
+
The Core API's CI lists every breaking change in a pull request before it merges, so the bump
|
|
188
|
+
is read off that list rather than judged. Before 1.0.0, a breaking change bumps the minor, as
|
|
189
|
+
semver allows for `0.x`.
|
|
190
|
+
|
|
191
|
+
The version describes your build, not the server. An API change reaches every client when it
|
|
192
|
+
deploys, whichever SDK version they run, so handle enum values your version does not list:
|
|
193
|
+
the types say which values exist today, not which ones a response can carry tomorrow.
|