Web service API should be designed and documented
|Branch:||Affected Dashboard version:|
Currently the application provides an incomplete and undocumented API. Unfortunately, various people are beginning to use these. Worse still, the report aggregator and node classifier use these undocumented APIs in incompatible ways across different Puppet releases.
- All actions, parameters and output formats should be documented and examples provided.
- All actions that emit data should be able to produce JSON, the preferred format for those working with web services.
- All actions that return lists of records should be paginated, e.g. fetching “/reports.json” should return a paginated subset of the reports data, rather than all reports. All paginated actions should emit a consistent field describing the number of pages and records matched. All actions doing pagination should accept a consistent set of parameters to retrieve records for a particular page.
Optional behavior: * Authenticity token cookie, as used by Rails, may be used to guard all non-GET actions as long as it’s easy to retrieve. * Site-specific token may be used to guard all non-GET actions.