I am deploying a FastAPI application to docker and I'm pondering how to best manage the Semantic Versioning.
Since it is just an API, I would think that MAJOR.MINOR.PATCH could be determined by comparing the previous builds OpenAPI Spec to the current builds OpenAPI Spec. If the request or response interface has changed, then increment the version accordingly.
Is this something that would work and is there something that already provides this functionality? If not, what approaches are used today to auto manage Semantic Versioning?
Thanks!
Related
Why not just make your backend api route start with /api?
Why do we want to have the /v1 bit? Why not just api/? Can you give a concrete example? What are the benefits of either?
One of the major challenges surrounding exposing services is handling updates to the API contract. Clients may not want to update their applications when the API changes, so a versioning strategy becomes crucial. A versioning strategy allows clients to continue using the existing REST API and migrate their applications to the newer API when they are ready.
There are four common ways to version a REST API.
Versioning through URI Path
http://www.example.com/api/1/products
REST API versioning through the URI path
One way to version a REST API is to include the version number in the URI path.
xMatters uses this strategy, and so do DevOps teams at Facebook, Twitter, Airbnb, and many more.
The internal version of the API uses the 1.2.3 format, so it looks as follows:
MAJOR.MINOR.PATCH
Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct host.
Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They are usually communicated in change logs to inform clients about a new functionality or a bug fix.
This solution often uses URI routing to point to a specific version of the API. Because cache keys (in this situation URIs) are changed by version, clients can easily cache resources. When a new version of the REST API is released, it is perceived as a new entry in the cache.
Pros: Clients can cache resources easily
Cons: This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API
Ref: https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/#:~:text=Clients%20may%20not%20want%20to,API%20when%20they%20are%20ready.
We are generating API documentation from the source code using Swagger. I am now wondering if there is any tool which automatically checks the compliance of the generated OpenAPI document (= Swagger JSON) to RESTful API design best practices.
For example Zalando has defined a publicly available guideline for REST-design In my opinion in these guideline there are many rules which can be check automatically based on the OpenAPI Specification:
“Don’t Break Backward Compatibility” could be check when OpenAPI
documents of different versions are compared.
“Always Return JSON Object as Top-Level Data Structures to Support
Extensibility"
“Keep URLs Verb-Free” could possible checked if compared with
dictionaries.
…
So far, I only found tools which checks the completeness and naming conventions of an OpenAPI document. Does someone know a tool with more advanced rules?
UPDATE:
Meanwhile I have found a tool called Zally (https://github.com/zalando-incubator/zally). This tool checks for violations of Zalando's REST-Api Guidelines. It is rather easy to configure or extend.
Some of these could be added as rules to openapilint. The backward compatibility check would need to compare two spec versions in search of differences, which is a bit more complex.
I am trying to implement versioning in my project. Requirement is to implement automatic semantic versioning(ex- 1.0.1). Just wanted to know, is there any way to implement semantic versioning automatically or we have to give semantic versions manually?
I am trying to save Json schemas in database with semantic versioning. So i am looking for implementing versioning at server side our at database level.
I have already used Hibernate envers to implement automatic versioning in form of 0,1,2.
Is there any other similar versioning technique which we can implement for automatic versioning?
If you're talking JavaScript then you could try semantic-release. It's a powerful system for automated package publishing that updates version numbers in your package.json based on git commit messages.
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
I am trying to build microservices with design first approach and using akka-http(scala) 2.4.1. For the design-first, IMHO, swagger is widely used. I couldn't find any boilerplate implementation as to how swagger works with akka-http.
How could I proceed?
I found a thread https://github.com/akka/akka/issues/16591 which talks about this to some extent, but couldn't find a conclusion / approach to take.
Also, there seems to be one not maintained version of a library https://github.com/Tecsisa/akka-http-swagger
In the swagger community, found a thread indicating to use swagger-inflector for ensuring the implementation is adhering to the swagger spec developed, but that seems to blend well with java and not with scala.