View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 1451 | RackTables | default | public | 2015-03-19 01:33 | 2015-05-19 17:43 |
| Reporter | jzohrab | Assigned To | |||
| Priority | normal | Severity | feature | Reproducibility | N/A |
| Status | new | Resolution | open | ||
| Summary | 1451: Add API versioning | ||||
| Description | RackTables needs to have proper API versioning to allow for developers to update/refactor existing code. This will likely be a big change affecting a fair amount of the internal code, but ideally it would add some clarity about application boundaries, and prepare the way for future development. This change would not and should not add any new features. As a result, it may be seen as extremely low priority from the community. I still think it's a good idea for long-term app longevity. I don't know if the system currently has a well-defined boundary for external interfaces (plug-ins and scripts). It appears that people can call pretty much whatever method they'd like. If the application "surface area" could be reduce, it would be easier to make changes to the internals. If we can limit this discussion to, say, wwwroot/inc/ajax-interface.php, then things become much easier. If people call whatever methods they'd like, either via plug-ins or scripts, then things get difficult, either for Racktables devs, or for the users. My feeling is that internals should be able to change. The application can't be expected to maintain all of its current method signatures as-is, that makes development far too difficult. If clients are only calling a handful of methods (eg through custom PHP scripts/plug-ins), then those methods could be pulled into another versioned interface as well, providing another public API. We'd need feedback on what users are actually calling. This helps set the boundaries of the application for its users ... hard to do once the thing is actually launched, but maybe necessary for the application's future health. Once the boundary is determined, there are a few ways to actually handle versioning, e.g., see long discussions at http://stackoverflow.com/questions/389169/best-practices-for-api-versioning and other places on API versioning. That will be the relatively easy part! | ||||
| Tags | No tags attached. | ||||
 |
Has anyone here ever used swagger (http://swagger.io)? It's really great for versioning and documentation. A single YAML file defines the API and you can really keep yourself honest with it. |
