[katello] API "contract"... when, if ever?

Tom_McKay1 · May 20, 2016, 8:11am

When, if ever, would be a good time to establish a documented API contract
for the body of GET json payloads?

A change was made recently[1] that broke a script[2] of mine. As a user, it
can be a difficult thing debugging why a script stopped working between
releases. Having a document defining the API json results and its migration
between releases (katello-3.0 to katello-3.1 presumably) would be a helpful
first reference.

Is this something we, developers, can begin to form a process and agreement
around?

[1]

This was part of needed performance improvements.
[2]

github.com

Katello/hammer-cli-csv/blob/master/lib/hammer_cli_csv/subscriptions.rb#L23


      
          end
          
          option %w(--in-portal), :flag, _('Import subscription comment lines into portal'),
                 :hidden => true
          option %w(--portal-username), 'PORTAL_USERNAME', 'Portal username',
                 :hidden => true
          option %w(--portal-password), 'PORTAL_PASSWORD', 'Portal password',
                 :hidden => true
          option %w(--portal-hock), 'PORTAL_HOCK', 'Portal subscription creation address',
                 :hidden => true
          option %w(--portal), 'PORTAL', 'Portal subscription access address',
                 :default => "https://subscription.rhn.redhat.com:443",
                 :hidden => true
          
          ORGANIZATION = 'Organization'
          MANIFEST = 'Manifest File'
          
          def export(csv)
            csv << [NAME, ORGANIZATION, MANIFEST, SUBS_NAME, SUBS_QUANTITY, SUBS_SKU, SUBS_CONTRACT, SUBS_ACCOUNT, SUBS_START, SUBS_END]
            @api.resource(:organizations).call(:index, {:per_page => 999999})['results'].each do |organization|
              next if option_organization && organization['name'] != option_organization

To be fair, this is not really a script but hammer-cli-csv is not in
any testing pipeline. It breaks very, very often since it relies on the API
and its json results. I think it is representative of an advanced customer
(ie. $$) script, though.

Tom_McKay1 · May 20, 2016, 8:56am

Probably a pretty big undertaking to test. Maybe record calls to VCR and
then diff? Are there tools to flag differences?

···

On Fri, May 20, 2016 at 4:11 AM, Tom McKay wrote:

When, if ever, would be a good time to establish a documented API contract
for the body of GET json payloads?

A change was made recently[1] that broke a script[2] of mine. As a user,
it can be a difficult thing debugging why a script stopped working between
releases. Having a document defining the API json results and its migration
between releases (katello-3.0 to katello-3.1 presumably) would be a helpful
first reference.

Is this something we, developers, can begin to form a process and
agreement around?

[1]
https://github.com/Katello/katello/commit/c11d6c0e#diff-d14df79e8e961a08a92ab350ed6d32b7L12
This was part of needed performance improvements.
[2]
https://github.com/Katello/hammer-cli-csv/blob/master/lib/hammer_cli_csv/subscriptions.rb#L23
To be fair, this is not really a script but hammer-cli-csv is not in
any testing pipeline. It breaks very, very often since it relies on the API
and its json results. I think it is representative of an advanced customer
(ie. $$) script, though.