"And it kind of sucks to describe JSON-based APIs in XML." Marsh Gardiner

[mail-2]

The quote is from: Better API Design with OpenAPI (Cloud Next '18) on YouTube

I admit the quote is only indirectly related to proxy design in Apigee but directly applicable none the less.

Are there any plans to offer YAML or other formats/languages as an option over XML for the proxy design? Good role-models could be IaC solutions like Terraform or CDK in my opinion.

My impression is that the XML based description is not adding any value what so ever and the decision for its choice was born out of IT methodologies which have died years ago.

Editing those XML files is a cumbersome nuisance (also again I don't see any XML-specific feature adding value to the process of designing Apigee proxies) and is holding back adoption of and passion for Apigee as a product. It's not like Apigee is leveraging any XML feature beyond the key/value aspect of it and specifying scopes with tags.

[dchiesa1]

There is a terraform provider for Apigee.

https://github.com/zambien/terraform-provider-apigee

I can't vouch for the quality or scope of this provider.

Editing those XML files is a cumbersome nuisance

I'm sorry you find XML to be so cumbersome. My experience is different than yours. In my mind it's just a markup. It's true that YAML is much more popular these days, and YAML is easier on the eyes, and often (not always) smaller. JSON is also popular, and I find it really easy to use. On the other hand, I've never seen a project fail because there are angle brackets in the configuration metadata.

Editing those XML files ... is holding back adoption of and passion for Apigee as a product

We think the capabilities of Apigee can be super valuable for people who want enterprise-grade API management for their companies. Exposing their assets and systems to be programmatically accessible via APIs, and getting management around those APIs, can be decisive. The format of the configuration data... is an implementation detail.

It's not like Apigee is leveraging any XML feature beyond the key/value aspect of it and specifying scopes with tags.

That's true. There may be some future plans to support alternative data formats. I'll invite the PMs to comment.

[mail-2]

> There is a terraform provider for Apigee.

Which shows there is a need for a different interface. But I'm not sure if I'd recommend a company to use this non-official solution. Also I'm not sure how well this can work given that Terraform is based on atomical API access. Apigee does not provide an API which allows individually and directly adding/removing/configuring policies in a proxy for example. That would have to be channeld through updating and deploying XML configs which seems iffy when it comes to rollbacks. (https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/apis/%7Bapi_name%7D/revisions/%7Brevision_number%7D-0)

There is a reason for why there's no XML used for infrastructure programmability on AWS or GCP.

> and YAML is easier on the eyes

Apigee proxies are developed manually by humans via editing config files - so that is a big deal! Nobody desires working with a language that is hard on the eyes. That's why Python became so popular. Other languages like R, Perl or Haskell are popular despite being difficult to read only because they allow very succinct expression. Another feature XML falls short of.

> JSON is also popular, and I find it really easy to use.

JSON would introduce the problem of having to maintain brackets which is similar to maintaining end-tags. YAML is popular because 4 spaces intuitively reveal the hierarchy to an onlooker.

> On the other hand, I've never seen a project fail because there are angle brackets in the configuration metadata.

At the risk of sounding pedantic Apigee configuration is not meta-data but data. It doesn't describe other data but describes the Apigee set-up via 1-on-1-mapping of tags to entities like policies, rules etc.

As such the choice of the format is not a detail but as important as language for human expression. Humans have psychological needs - if you want talented developers work with Apigee then the development process should be somewhat fun and not tiring. There is a reason why SOAP is on the way out and XML+XSL never replaced HTML.

> We think the capabilities of Apigee can be super valuable for people who want enterprise-grade API management for their companies.

It seems to me that you are associating "enterprise-grade" with XML which would be big mistake. Except for applications where XML actually is superior (mostly where XML is produced _and_ consumed by programs) it is often falsely considered enterprisey for some weird reason only tech-averse managers are competent to explain.

> The format of the configuration data... is an implementation detail.

Not at all - because those configuration files are developed by humans. And we're not talking here about setting a few values here and there but editing lots and lots of large files.

Also with regard to Apigee promoting best practices - XML is infamous for being very difficult to sanely version (https://stackoverflow.com/a/2041050). That is another important point where XML fails to deliver.

[dchiesa1]

It seems to me that you are associating "enterprise-grade" with XML which would be big mistake.

I am not. I am saying Apigee capabilities, aside from how the configuration is specified, is valued by many companies for high quality and breadth. And if some of the people at those companies don't prefer the XML, which I'm sure is true, they still use Apigee and get benefit out of it.

I appreciate your feedback around Apigee's use of XML, and how to improve it.

[mail-2]

And I appreciate you taking the time to respond. I also know that developing a highly complex system like Apigee always comes with compromises and decisions that receive criticism. It is not my intention to belittle the expertise and work that went into developing Apigee in any way.

[Marsh]

I came to say, "You twisted my words!" but upon reading more carefully, I see that you did that already for me, thanks.

Yes, my original point was that in 2010-11 the state-of-the-art API description format was arguably the XML-based WADL, which set the stage for the rise of JSON and then YAML for describing APIs in a formal way.

We have explored using spec extensions in OpenAPI to handle some configuration options within the API spec. Would that be useful to you, or are you preferring a separate configuration file in YAML (or similar) instead of XML?

[mail-2]

> We have explored using spec extensions in OpenAPI to handle some configuration options within the API spec. Would that be useful to you [...]?

If I understand this correctly then I'd say that would be useful for sure but is not related to my opinion piece above. I'm directly referring to the configuration/programming of an Apigee product/proxy infrastructure.

> or are you preferring a separate configuration file in YAML (or similar) instead of XML?

As I describe below - YAML would only be an option that comes to mind and is quite popular (vs other formats that have to be edited/crafted by humans).

Other possible directions are shown by IoC solutions like CDK or Terraform.

To summarize my point (which I explain below with some examples) is that XML comes like every thing in life with advantages and disadvantages. But it seems that Apigee is not using any of the advantages - so what's left is the disadvantages.