Abstract
In an ideal world, we wouldn’t need explicit version numbers (or any version identifiers for that matter) in our REST APIs. If you think that such a world doesn’t exist, well, it is all around us. It is the Web! Our web browsers can handle all sorts of web sites, usually without significant problems (we assume that our modern browser understands different dialects of HTML, and the site is not specifically targeted for another browser). Part of the magic stems from hypermedia controls embedded in an HTML content. Take a look at the source HTML (try to load some complex web page into your browser, and ask it to show the page source), and you will encounter all sorts of links to other web pages, various forms for uploading data, as well as forms for performing custom searches, and so on.
This is a preview of subscription content, log in via an institution to check access.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Notes
- 1.
Maven efficiently handles dependencies for the compilation phase, but the runtime might be different (via the provided and system scopes). For example, in the case of OSGi, just plain Maven versioning might not be enough.
- 2.
I’ve also seen quite an “extreme” approach in the industry, where the first version of the service is released without any versioning at all (a common mistake in any API). For example, even OSGi gurus (who are very scrupulous about versioning) have made the same mistake (see http://wiki.apidesign.org/wiki/PropertyFiles ). At first glance, this might sound ingenious, but under the hood it silently acknowledges the URL versioning scheme. At any rate, I recommend you make a firm decision about versioning before releasing the first production system. The versioning scheme must be part of an API from the very beginning.
- 3.
This conundrum is similar to the situation regarding what kind of authentication to use in a REST service. General advice is to start with OAuth in mind as early as possible, because switching an authentication scheme isn’t a straightforward process (in addition, it is an incompatible change for a production system).
- 4.
In case of Java, this would be similar to releasing a new version of an API inside a different package. That is a brute force coexistence (see http://wiki.apidesign.org/wiki/Co-existence ), but is probably better than perpetrating incompatible changes.
- 5.
Sometimes you will bump into dates instead of familiar version identifiers. For a REST API it is more natural to have version identifiers, as mentioned in this book. However, Semantic Web documents are better controlled via dates, as the Semantic Web technology primarily deals with vocabularies and descriptions rather than service implementations.
- 6.
This is an interesting question in modular design, too. Should we version each module independently, or rather mark the whole release with a single version? The answer depends on the use case: If you want to plug a module into some version of the product, then it is easier to have a uniform version number for all the modules. However, if you are building reusable modules, which are also leveraged inside an application, then it is better to have a separate version for each of them.
- 7.
The uniform resource name (URN), which was used for a stable name, is deprecated in favor of the URI.
- 8.
Stay away from premature conclusions whether this URI is also a URL. Having http inside it doesn’t inevitably mean it is a URL. You need to be able to resolve that address, and get back an apt representation to qualify it as a URL. The HTTP 404 Not Found response isn’t a viable representation, though.
- 9.
Instead of a URI, a company could also use a more generic internationalized resource identifier (IRI), defined in RFC 3987 (see https://tools.ietf.org/html/rfc3987 ). Furthermore, by exposing a SPARQL endpoint (usually at the relative URL of /sparql), anyone could issue DESCRIBE <Company's IRI> to get RDF descriptions about that resource. You can read more about the SPARQL protocol and query language at http://www.w3.org/TR/sparql11-protocol/ and http://www.w3.org/TR/sparql11-query/ , respectively. It is even possible to translate terms (implement the dictionary from Chapter 16) by using the CONSTRUCT instruction.
Author information
Authors and Affiliations
Rights and permissions
Copyright information
© 2016 Ervin Varga
About this chapter
Cite this chapter
Varga, E. (2016). Versioning REST APIs. In: Creating Maintainable APIs. Apress, Berkeley, CA. https://doi.org/10.1007/978-1-4842-2196-9_6
Download citation
DOI: https://doi.org/10.1007/978-1-4842-2196-9_6
Published:
Publisher Name: Apress, Berkeley, CA
Print ISBN: 978-1-4842-2195-2
Online ISBN: 978-1-4842-2196-9
eBook Packages: Professional and Applied ComputingProfessional and Applied Computing (R0)Apress Access Books