[MGNLREST-64] Magnolia's REST API naming convention does not match Swagger's Created: 22/Jul/15  Updated: 25/Mar/22

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

Type: Bug Priority: Neutral
Reporter: Will Scheidegger Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

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)
Bug DoR:
[ ]* Steps to reproduce, expected, and actual results filled
[ ]* Affected version filled
Date of First Response:

 Description   

Swagger expects the first segment of the REST API to be the version, followed by the endpoint name, e.g.

/v1/shop/...

However in Magnolia's REST API this is flipped:

/nodes/v1/...

Because of this, Swagger lists all 3 Magnolia REST APIs (commands, properties and nodes) as "v1" and when you click on one of them all three are expanded. Maybe it would be a good thing to change this for v2?



 Comments   
Comment by Jan Haderka [ 13/Oct/16 ]

It's a pity that swagger acts that way, but it is by no means "standard".
However, there are many posts arguing for versioning whole API and not individual end points. Eg. http://programmers.stackexchange.com/questions/138455/what-is-a-recommended-pattern-for-rest-endpoints-planning-for-foresighted-change

I believe decision behind having version for individual rest points was conscious as those can be provided by different modules and each modules was "given" freedom to roll out new version as they need.

That said, I don't really see easy way out w/o any drawbacks.

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