Merge pull request #179 from alien-mcl/issue/72_Discuss_versioning

Discuss versioning
HydraCG · Feb 3, 2019 · e951bd9 · e951bd9
2 parents 1568b7f + 8a246c5
commit e951bd9
Showing 1 changed file with 17 additions and 0 deletions.
diff --git a/spec/latest/core/index.html b/spec/latest/core/index.html
@@ -683,6 +683,23 @@ <h3>Documenting a Web API</h3>
       -->
     </pre>
   </section>
+
+  <section>
+    <h3>Api versions</h3>
+
+    <p>It is common to provide a separate API address after a breaking changes
+      update. This prevents current clients not to get broken as these may not
+      support these changes.</p>
+
+    <p>With hypermedia provided in each response payload, it may be unnecessary
+      to provide such an alternative API. This is due to fact the client follows
+      what the server provides and with proper margin for errors implemented
+      within that client, even breaking changes can be published on the fly.</p>
+
+    <p>Still, Hydra does neither have any special support for API versions, nor
+      prevents them. It's fully an implementers decision on if and how
+      to provide the API features.</p>
+  </section>
 </section>
 
 <section>