Does anybody know what is Group versioning in REST API?
I found the link below where it explains it, but i don't understand how to use it.
I am looking for:
How to configure group version across multiple endpoints ?
Can someone provide practical example of it ?
Github Microsoft API guidelines
Despite the vernacular, Group versioning is really nothing more than versioning by date. Most, if not all, Azure services version this way. You can choose whether you want to version by number or date - the two most common formats. Versioning by Group (e.g. date) is convenient for services. You know exactly when things were released. It can be difficult to track when a numeric version was deployed over time. Whether you map the group to some internal value is up to you, but I would claim it doesn't bring you anything but complexity and confusion. If you use a date for your version number, embrace it through and through.
The guidelines somewhat imply that you can have varying minor versions mapping to a single group (e.g. date); that could be dangerous. It's generally assumed that a minor version is backward compatible; however, a service should never assume that this is true. A service has no control over a client and their ability to handle even additive content (e.g. tolerant reader). The only type of versioning behind a group that should ever be done is patching, which has no visible wire protocol differences. You'll have to decide if it's worth mapping patch versions to groups/dates internally.
Whether you choose to version by number, date, or even both, is up to you. ASP.NET API Versioning is one such realization of these guidelines. It also includes support for a status (ex: Beta), which no longer appears in the formal REST guidelines. The wiki contains in-depth details.
I hope that helps.
Related
I'm learning about the REST architecture style, and there are some things I don't understand when it comes to developing a back-end api for clients.
I've read about various approaches to versioning an http api, which all make sense, but how do you indicate to a client, when he's using an outdated version of your api, that he needs to update his version? Is there a way to do this without physically contacting the client and telling him that he needs to update his version?
I was thinking there might be some way to require the client to indicate his current version and give an appropriate message if it's outdated. Is this standard or even feasible?
Typically, clients update under one of two circumstances. Either they want functionality that's available in a more recent version, or you're dropping support for a prior version.
If you're planning on dropping support for an API version, you should definitely be notifying any customers you can find proactively. If they rely on your API version, and it disappears with no warning, they're going to be former customers.
In the vast majority of cases, clients of your API will not be scanning network traffic looking for a header or other indicator that the API is changing. Asking them to do so is non-standard and almost certainly not feasible.
Also, dropping support for an API version is a major shift. It causes upheaval in all of your clients, forcing them to make a code change in their applications by a date of your choice. It's not something to be done lightly.
The Reliable Services Overview topic has a section, at the bottom, called When to use Reliable Services APIs. In there, one list item says:
Your application needs to maintain change history for its units of state*.
The star at the end is explained just a little bit further down:
* Features available at SDK general availability.
The SDK has reached general availability by now, but I cannot find any information about how to make use of the "Maintain change history for its units of state"-feature or even a suggestion of what that actually means.
I'm asking here, in hope that someone can shed any light on this. I'm interested in knowing whether this feature is indeed available, or if not when it is supposed to be available, or if it has been abandoned.
Some insights on the intended design and functionality of this feature would also be much appreciated.
It describes the scenarios in which you might use the reliable collections. It can be used to keep multiple versions of an object and build a history of changes. (like delta's or snapshots)
This way you can create an event source. (it would require some coding on your end though)
Unit of state: entry in the State manager
I've been reading up on versioning strategies for ReST APIs, and something none of them appear to address is how you manage the underlying codebase.
Let's say we're making a bunch of breaking changes to an API - for example, changing our Customer resource so that it returns separate forename and surname fields instead of a single name field. (For this example, I'll use the URL versioning solution since it's easy to understand the concepts involved, but the question is equally applicable to content negotiation or custom HTTP headers)
We now have an endpoint at http://api.mycompany.com/v1/customers/{id}, and another incompatible endpoint at http://api.mycompany.com/v2/customers/{id}. We are still releasing bugfixes and security updates to the v1 API, but new feature development is now all focusing on v2. How do we write, test and deploy changes to our API server? I can see at least two solutions:
Use a source control branch/tag for the v1 codebase. v1 and v2 are developed, and deployed independently, with revision control merges used as necessary to apply the same bugfix to both versions - similar to how you'd manage codebases for native apps when developing a major new version whilst still supporting the previous version.
Make the codebase itself aware of the API versions, so you end up with a single codebase that includes both the v1 customer representation and the v2 customer representation. Treat versioning as part of your solution architecture instead of a deployment issue - probably using some combination of namespaces and routing to make sure requests are handled by the correct version.
The obvious advantage of the branch model is that it's trivial to delete old API versions - just stop deploying the appropriate branch/tag - but if you're running several versions, you could end up with a really convoluted branch structure and deployment pipeline. The "unified codebase" model avoids this problem, but (I think?) would make it much harder to remove deprecated resources and endpoints from the codebase when they're no longer required. I know this is probably subjective since there's unlikely to be a simple correct answer, but I'm curious to understand how organisations who maintain complex APIs across multiple versions are solving this problem.
I've used both of the strategies you mention. Of those two, I favor the second approach, being simpler, in use cases that support it. That is, if the versioning needs are simple, then go with a simpler software design:
A low number of changes, low complexity changes, or low frequency change schedule
Changes that are largely orthogonal to the rest of the codebase: the public API can exist peacefully with the rest of the stack without requiring "excessive" (for whatever definition of of that term you choose to adopt) branching in code
I did not find it overly difficult to remove deprecated versions using this model:
Good test coverage meant that ripping out a retired API and the associated backing code ensured no (well, minimal) regressions
Good naming strategy (API-versioned package names, or somewhat uglier, API versions in method names) made it easy to locate the relevant code
Cross-cutting concerns are harder; modifications to core backend systems to support multiple APIs have to be very carefully weighed. At some point, the cost of versioning backend (See comment on "excessive" above) outweighs the benefit of a single codebase.
The first approach is certainly simpler from the standpoint of reducing conflict between co-existing versions, but the overhead of maintaining separate systems tended to outweigh the benefit of reducing version conflict. That said, it was dead simple to stand up a new public API stack and start iterating on a separate API branch. Of course, generational loss set in almost immediately, and the branches turned into a mess of merges, merge conflict resolutions, and other such fun.
A third approach is at the architectural layer: adopt a variant of the Facade pattern, and abstract your APIs into public facing, versioned layers that talks to the appropriate Facade instance, which in turn talks to the backend via its own set of APIs. Your Facade (I used an Adapter in my previous project) becomes its own package, self-contained and testable, and allows you to migrate frontend APIs independently of the backend, and of each other.
This will work if your API versions tend to expose the same kinds of resources, but with different structural representations, as in your fullname/forename/surname example. It gets slightly harder if they start relying on different backend computations, as in, "My backend service has returned incorrectly calculated compound interest that has been exposed in public API v1. Our customers have already patched this incorrect behavior. Therefore, I cannot update that computation in the backend and have it apply until v2. Therefore we now need to fork our interest calculation code." Luckily, those tend to be infrequent: practically speaking, consumers of RESTful APIs favor accurate resource representations over bug-for-bug backwards compatibility, even amongst non-breaking changes on a theoretically idempotent GETted resource.
I'll be interested to hear your eventual decision.
For me the second approach is better. I have use it for the SOAP web services and plan to use it for REST also.
As you write, the codebase should be version aware, but a compatibility layer can be used as separate layer. In your example, the codebase can produce resource representation (JSON or XML) with first and last name, but the compatibility layer will change it to have only name instead.
The codebase should implement only the latest version, lets say v3. The compatibility layer should convert the requests and response between the newest version v3 and the supported versions e.g v1 and v2.
The compatibility layer can have a separate adapters for each supported version which can be connected as chain.
For example:
Client v1 request: v1 adapt to v2 ---> v2 adapt to v3 ----> codebase
Client v2 request: v1 adapt to v2 (skip) ---> v2 adapt to v3 ----> codebase
For the response the adapters function simply in the opposite direction. If you are using Java EE, you can you the servlet filter chain as adapter chain for example.
Removing one version is easy, delete the corresponding adapter and the test code.
Branching seems much better for me, and i used this approach in my case.
Yes as you already mentioned - backporting bug fixes will require some effort, but at the same time supporting multiple versions under one source base (with routing and all other stuff) will require you if not less, but at least same effort, making system more complicated and monstrous with different branches of logic inside (at some point of versioning you definetely will come to huge case() pointing to version modules having code duplicated, or having even worse if(version == 2) then...) .
Also dont forget that for regression purposes you still have to keep tests branched.
Regarding versioning policy: i would keep as max -2 versions from current, deprecating support for old ones - that would give some motivation for users to move.
Usually, introduction of a major version of API leading you in a situation of having to maintain multiple versions is an event which does not (or should not) occur very frequently. However, it cannot be avoided completely. I think it is overall a safe assumption that a major version, once introduced, would stay latest version for relatively long period of time. Based on this, I would prefer to achieve simplicity in the code at the expense of duplication as it gives me better confidence of not breaking previous version when I introduce changes in latest one.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I need some experiences concerning the writing of software documentations and user guides.
When I write formal documents like software specifications, every document gets a version number and in the document there is a change history after the table of contents, where you can keep track of the changes made to the document.
If I'm now writing a software documentation or a user guide for an application, and the software has versioning itself, one could get confused with the version number of the document and the product: e.g. application version 1.5, documentation version 1.3.
What's the common way / best practice to write software documentation? Do you keep track of changes to the documents there? If you print a change history - do you show changes to the product and/or the document?
I've encountered this issue at every company for which I've worked that 1) had a significant code base, 2) attempted professional quality documentation, and 3) had separate development and documentation groups.
I have come to agree with Anders, convinced that software and documentation should have different versioning and version control systems. Although similar and having the same target, documentation and code have different lifecycles, which can be fully independent, only being mapped one to the other at release time.
As for generating the documentation with each software build, ask yourself: does that really make sense? Is the documentation historical or is it prescriptive? Any documentation that is generated with each build better have the tools in place to do it. Currently, that only works for API documentation and there are Doxygen-/Javadoc-style tools to support it. That is likely to never be doable for User's Guides and Installation Guides because they are context sensitive.
The need for different version control systems holds, particularly, for the newer structured documentation methodologies. Structured documentation needs to be managed at a much finer level of granularity than source code to be able to efficiently handle something even as seemingly simple as rebranding; usually managed at either the paragraph, sentence, or word level, unlike the file level, which is sufficient for source code. Further, it is generally economical for document elements to be shared among multiple products or departments (engineering, marketing, ...). And, for this level of documentation sophistication, only a content management system is sufficient for tracking content and managing change; the CVS-/SVN-/Perforce-/Clearcase-style SCCSs are abysmally inadequate for managing real-world documentation. Using different version management tools ensures different version numbers for documentation and software.
Documentation may even have a higher rate of change than software when the need for handling typos, grammar errors, and corporate style changes is considered.
Separating documentation and development processes reduces dependencies, which is the fundamental metric needed for producing a quality product. Further, late binding is desirable to best accommodate the rapid rate of change and unpredictable events like late feature additions or deletions. Only at the moment of final (or alpha-/beta release) should the documentation version be mapped to the software version. But, I agree with High-Performance Mark that the end user shouldn't see different version numbers. The documentation version number does not need to appear on the document. That number can, within the documentation process, be maintained and hidden from the public.
The only time that software and documentation versioning can be maintained in lockstep is when documentation is a fully-integrated part of the development process. Over the last 30 years, I've seen this becoming less and less the case because there is less formal, upfront design than there used to be, relying, instead, on an iterative, quick-prototyping approach to software development. The original well-intentioned notions of having documentation drive software development have mostly been put aside but the new methodology also hasn't given us improved documentation or software. Whether the documentation is done upfront or as an afterthought, it's still going to double the time it takes to develop a commercial-quality product.
I think that the documentation and the software are different items, which each have different version numbers. You want to be able to update the documentation without having to update the software number. I would have named it something like:
System Documentation for productX 1.3
Documentation revision 1.7
By clearly including both the software version and the document version in the same place there shouldn't be any confusion.
We tend to use a plain text format for our documentation, mainly LaTeX, and treat it just like source code from a revision point of view: it goes in the repo, we can do diffs and patches, etc. We're not big for change histories in published documents, we can always audit what has gone on if necessary but it rarely is.
As for synchronising code and documentation version numbers, our preferred approach is that v1.1.1 of a document matches v1.1.1 of the software, 3.2.45 matches 3.2.45 and so on. However, in practice we often only have documentation for the first 2 digits (ie 1.1, 3.2) since the third digit is mainly for bug-fixes or performance enhancements. The repo revision number is inserted into the documentation (and in the source code) using svn:keywords should we ever need it.
I'd like to tell you that the same makefile which builds our new version software also builds the new version of the documentation, but we haven't got there yet. We are, however, working on it.
Why don't you just use version control and use that as the automatic document revision? You can have most systems update some text on checkout.
Taken aback to day when I was confronted about the use of validation code used from the Csla framework. It felt like I was reprimanded for not disclosing the use of the framework to the client.
Is this not the same as using libraries such as jQuery etc?
You absolutely should acknowledge what you're using, IMO.
Some clients may have particularly strict legal requirements (whether for legitimate reasons or not - they're the client, it's not up to you to judge their laywers) and detailing any third party software you're using to create a product for them seems only reasonable.
What reason could you have for not wanting to be open with your client?
This depends on the license of the open source code you are using. Many of them require to acknowledge the use in some credits section, others require you to redistribute the source code, etc. You should read the license and act accordingly.
It depends on the project and the kind of client and whatever contracts you had. However, for a typical consultant delivering code to a customer, I would say no it is very strange that you would be reprimanded for not bothering them with details such as the use of CSLA. That's pretty odd.
It is the same, I have a feeling that you would have been reprimanded for using jQuery as well. There are enterprises that frown upon the use of open source for various reasons.
They boil down to
The type of license and what does it force the user to do
The availability of support in some commercial form
The need to 'share-alike' the results
You should know what's your customer/employer's stance on this. If they don't have a stance, then you have to discuss on a case-by-case basis.
I usually tell people I use a lot of open source and, by seeing the response I get I know the path to follow. If they jump and scream at the mention of open source and the lack of support and whatnot, I just tend to ask for budget to buy commercial components or present good cases as to why the open source version of X is better than the commercial alternatives.
It very much depends on the type of project and the type of client. The real problem here is that you were surprised, which indicates non-alignment of expectations. How did the client motivate its interest in Csla specifically?
If your client needs to know or cares about which technology you use, then you should specify everything as part of the project documentation. If the choices are clearly described, then it is easier to have a discussion about them, if required. Documentation also gives you a way to ask (literally) for 'sign-off', if that is the way you work.
From your question it is not clear whether the problem was the choice of framework, or not having informed the customer.
Even on projects with minimal documentation, if the customer owns the code then I always deliver at least a High-level architecture document that includes the names and exact versions of every software component used, along with a brief description of what it is for and why it was selected. This is also the correct place to address any license issues.