Review XML vs. JSON response and request parameters of the Account Management API (mainly, but this might be extended to the other APIs), and come up with a plan to make the JSON endpoints better, at least by providing full documentation of requests and responses and filling in any omitted parameters that exist in XML responses but don't in JSON. The paragraphs below describe the current state of affairs with known issues and potential actions we can take to improve them.

The JSON version of the API is not fully equivalent to the XML one because one of the design principles taken was making it less expensive to avoid loading System and the database. This means that there are some important differences in terms of using references to related objects rather than embedding them in responses (which is what XML does, by paying the extra performance price of retrieving them), and because the code paths differ, there are also minor differences in terms of missing or different fields, or weird behavior (THREESCALE-5095). Unfortunately that decision makes it impractical to write a format-independent client to the API, so we might as well consider these different versions of the API.

One of the main problems when using these APIs is the documentation offered by the product help/documentation pages, which has a few serious issues. First, it is almost exclusively available for the XML endpoints (and then there are some endpoints only existing in JSON, but that is not a problem unless someone wants to deal exclusively with XML, which is rare these days). Second, only request fields are documented (not responses) and even then descriptions are sometimes lacking in cases where such fields are restricted to accept or adopt specific values, ie. a field named "environment" accepting "staging" and "production", but not "foobar", but developers being unaware. Finally, the configuration of your account and services determines whether some response fields are included or specified in a meaningful way, which coupled to the lack of response documentation, means there is no way to know the full set of fields that can appear in a response nor their types and potential values, ie. some field "foobar" might only show up when you turn on the feature FooBar, or it might be an object with a value of null when such a feature is off, which tells API client developers nothing about their structure or what information is hosted there. Importantly, this last issue is fixed by adding the relevant documentation.

Finally, there is one additional difficulty, which is that any change to these APIs is that people already depend on them, so any change must be non-breaking, as Marta pointed out in THREESCALE-5212.

In terms of documentation, the JSON API is using rspec_api_documentation, which can be leveraged to help document it via the API specs because it can generate an HTML description, while at the same time it can help in keeping the docs updated. Alternatively, or in addition to the previous option, we could review and expand the existing Swagger documentation, and create a new OpenAPI definition of the Account Management API (at least for the JSON API, which should be what we'll want people to use). Fixing issues with missing fields when comparing XML and JSON endpoints is something that can also be done when reviewing documentation.

Longer term there is the decision about what to do regarding these APIs. Keep supporting the XML version? Keep backwards-compatibility in the JSON one? Create a new version, scope it somehow to avoid clashes with the previous ones, and take the opportunity to do breaking changes and review the API design? Keep the better state of affairs until a completely revised, new data model is used in 3scale, which would come with its own different API?

Reference: this slack thread.

[[alex: edited to include description of issues + potential actionable options]]

— copied from duplicate issue THREESCALE-5715 (2020) —

The RHMI workload app uses the following API endpoints, including a few of the XML ones, that do not have good json equivalents

XML

• ${API_URL}/signup.xml (POST)
• ${API_URL}/services.xml (POST)
• ${API_URL}/services/${service_id}/application_plans.xml (POST)

• ${API_URL}/accounts/${account_id}/applications.xml (POST)
• ${API_URL}/services/${service_id}/proxy/deploy.xml (POST)
• ${API_URL}/services/${id}.xml (DELETE)
• ${API_URL}/accounts/${id}.xml (DELETE)
   
  [1] https://github.com/integr8ly/workload-web-app/blob/master/deploy/3scale.sh

See also this comment from 2019.