[MGNLREST-115] All endpoints are versioned Created: 13/Sep/17  Updated: 02/Nov/17  Resolved: 30/Oct/17

Status: Closed
Project: Magnolia REST Framework
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Story Priority: Neutral
Reporter: Christopher Zimmermann Assignee: Unassigned
Resolution: Done Votes: 0
Labels: to-estimate
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
dependency
depends upon MGNLREST-116 Support multiple configured endpoint ... Closed
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Date of First Response:
Epic Link: REST Queries
Sprint: Saigon 116, Saigon 117, Saigon 118, Saigon 119, Saigon 120

 Description   

All of the new endpoints should be versioned.

User stories:

  • As a Developer at Magnolia, I can make changes and improvements to our REST endpoints without fear of breaking existing client projects.
  • As a Developer using Magnolia endpoints, I know that my projects will continue to work without any changes or migrations, even as Magnolia introduces changes to new versions of the endpoints.

Capabilities:

  • Magnolia developers can create multiple versions of the endpoints - both the OOTB ones and the technology that underlies the configurable endpoints.
  • Developers using Magnolia can specifiy which version of the Magnolia endpoint to use. (Possibly developers specify a version number as part of an API path or as a request header for an endpoint.) Magnolia can then introduce new versions of endpoints when we see a need for a change in the response or the querying.
  • Multiple versions of the endpoint must be available simultaniously on the same system.
  • Developers using Magnolia can also version the custom endpoints that they create. So that they too can improve their endpoints over time without breaking applications that rely on them.

Scenario
For example imagine magnolia provides v1 of our endpoint system. Customer "Bob" creates endpoint "bob/v1" on his Magnolia project. Then 3 frontend apps are developed which use that endpoint. Then Bob wants to create a cooler endpoint format and so releases "bob/v2". The frontend apps continue to work - and one of them upgrades to use "bob/v2".

Next Magnolia realizes we should really rename one of our properties and we release v2 of our endpoint system. All of bobs app continue to work because v1 is still supported. Bob is cool so he also creates "bob/v3" which implements our v2 output. And finally one of the frontend apps also upgrades to "bob/v3" while the others contineu to use v2 and v1. After a deprecation grace period,(and probably looking at his REST analytics that noone uses v1 anymore) Bob finally removes his v1 endpoint.

Nice examples of the kinds of things that can change over time:
https://stripe.com/docs/upgrades#api-changelog



 Comments   
Comment by Mikaël Geljić [ 30/Oct/17 ]

all current endpoints are already versioned in path.

Generated at Mon Feb 12 06:56:45 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.