Updating the latest public fabric v4 [4.6] API specifications #18
Conversation
djoshi0
commented
Mar 28, 2023
•
djoshi0
commented
- Updated the Equinix Fabric V4 API specifications - version 4.6 -- [https://app.swaggerhub.com/apiproxy/registry/equinix-api/fabric/4.6]
- All the existing patches are applied in the updated specifications, hence the patch files are removed and readme updated
| # Fetch any public available version of Fabric V4 API specification. Send the URL to the specification as input argument | ||
| # Example: make fetch OPENAPI_URL=https://app.swaggerhub.com/apiproxy/registry/equinix-api/fabric/4.6 | ||
| fetch: | ||
| curl ${OPENAPI_URL} | jq . > ${SPEC_FETCHED_FILE} |
There was a problem hiding this comment.
Let's define this in the Makefile (around line 14) similar to https://github.com/equinix-labs/metal-java/blob/main/Makefile#L10-L11
OPENAPI_URL=https://app.swaggerhub.com/apiproxy/registry/equinix-api/fabric/4.6
spec/oas3.fabric.config.json
Outdated
| @@ -1,7 +1,7 @@ | |||
| { | |||
| "groupId": "com.equinix", | |||
| "artifactId": "equinix-openapi-fabric", | |||
| "artifactVersion": "1.0.0", | |||
| "artifactVersion": "4.6", | |||
There was a problem hiding this comment.
This would be a move away from semantic versioning. Does the upstream API have an API patch revision? If it does then we should represent that full version in this project. This repo would then need to represent the fabric-java revision or build as a suffix to the upstream semver version: v4.6.0-1
Alternatively, if the upstream API is only expressed as x.y, we could use .z to represent the fabric-java release of that artifact release.
In either of these scenarios, breaking changes in the SDK, introduced through codegen changes rather than upstream API spec changes, will not be reflected through semver.
There was a problem hiding this comment.
Sounds good. Let`s use the versioning of the artifact to have x.y.z where z represents the patch version.
Change done.
There was a problem hiding this comment.
We had some followup conversation in Slack based on how this field is used, how the Equinix Fabric API is versioned, and how changes to this SDK may be versioned independently of the Fabric API.
artifactVersion | artifact version in generated pom.xml. This also becomes part of the generated library's filename
The version that we'll use in this project will start with v0.1.0 as a semver release and we can update that version according to ANY change in this SDK (Makefile, patches, docs, upstream API). By keeping the revision under v1, we can make large changes to the SDK without disturbing user expectation (v0 implies all changes are possible).
We will include the Equinix Fabric API version in the package description and we can introduce SDK version updates to newer versions of the Fabric API, for example, a hypothetical release history:
| API Version | SDK Release | Latest Commit Message |
|---|---|---|
| 4.6 | v0.1.0 | Initial SDK release for Fabric 4.6 |
| 4.6 | v0.2.0 | SDK models moved to com.equinix.more.fabric from com.equinix.openapi.fabric |
| 4.6 | v0.2.1 | makefile fixed to correct errors in the documentation |
| 4.7 | v0.3.0 | Fabric API spec updated to 4.7 and code regenerated |
We can always move up to a v4.6+ semver for the SDK later if we feel that is a more appropriate pattern. If we choose to follow that pattern, we may use v4.6.0 (0 as the patch release because the upstream API does not publish a patch release number) with a suffix such as -build.{sdk semver}.
Other alternatives considered were to include a <properties><version> element in the POM.
…to GitHub packages
