JSON sample files for the EDP API¶
https://blueprints.launchpad.net/sahara/+spec/edp-api-json-samples
Provide sample JSON files for all EDP Sahara APIs to facilitate ease of use by command-line users.
Problem description¶
As an End User who prefers the Sahara CLI to its UI, I want a set of pre-constructed example JSON payloads for the Sahara EDP API so that I can easily learn the expected API signatures and modify them for my use.
Proposed change¶
Example JSON payloads will be added to the directory
sahara/etc/edp-examples/json-api-examples/v1.1, with a subpath for each
relevant manager (data_source, job, job_binary, job_binary_internals, and
job_execution.) It is intended that examples for future API versions will
follow this path structure.
Each file will be named after the pattern: method_name.[variety.]json,
where variety is optional and will be used to describe independently useful
variations in payloads for one method (as in varying engines underlying
data sources or processing jobs.)
Alternatives¶
A tool could conceivably be created to generate template payloads from the jsonschemata themselves. However, as the core use of this change is to provide immediately available, semantically valid payloads for ease of adoption, it is proposed that providing raw examples will better meet the perceived user need.
It would also be possible to package these examples directly with the python-saharaclient repository, an option which has much to recommend it. However, as these examples are globally useful to any non-UI interface, as they are reliant on the jsonschemata in the core repository for testing, and as the extant etc/edp-examples path is a natural home for them, placing them in the sahara repository itself seems indicated.
Data model impact¶
None.
REST API impact¶
None.
Other end user impact¶
None, though it is intended that the payloads may be used via the python-saharaclient.
Deployer impact¶
None.
Developer impact¶
None.
Sahara-image-elements impact¶
None.
Sahara-dashboard / Horizon impact¶
None.
Implementation¶
Assignee(s)¶
- Primary assignee:
egafford
- Other contributors:
tmckay (primary review)
Work Items¶
Payload generation: data_source
Payload generation: job
Payload generation: job_binary
Payload generation: job_binary_internals
Payload generation: job_execution
Addition of schema validation unit tests for all the above.
Dependencies¶
None.
Testing¶
After discussion with croberts and tmckay, it is proposed that integration testing is in this case unnecessary; these examples constitute documentation. While exhaustive testing is possible in this case, the resultant bloat of the CI build would be disproportionate to the utility of the change.
Unit testing will validate that these resources pass schema validation for their intended APIs.
Documentation Impact¶
This task is itself a documentation effort. A README.rst will be provided in place, in keeping with pre-existent etc/edp-examples.
