General overview of current problems with the specs

[glhrmv]

Hi all,

The current state of the Open API specs provided - which are linked in the README for some reason by the way, but why aren't they files maintained in this repo? - is valid and spec compliant, but it lacks the polish and clarity you'd expect from a production-grade, SDK-generating spec.

This last part is very significant: Contentstack maintains a set of SDKs in several languages which are manually developed rather than automatically generated, which adds a lot of friction when synchronising all of the SDKs in the target languages and when the underlying API changes (e.g. new functionality is added to existing endpoints, new endpoints are added, etc.). If the Open API specs were cleaner and more idiomatic, the company could just maintain the spec itself and generate all of the client SDKs (for current and possibly more supported languages) with a single automatic code generation tool.

One example is the operationId parameter. While they are unique across endpoints, they are all in lowercase (the format recommends camelCase) and in some cases they are unwieldy. Operation IDs like getallentries|getallentryvariants|equalsoperator|... violate the principle that operationId should be a unique and concise identifier for codegen and SDK generation.

Another example: many parameter descriptions are inaccurate or copy-pasted (e.g. "Enter the actual query that will be executed..." appears for fields that are not JSON queries).

One more: parameter names like include[] and only[BASE][] are technically allowed, but not idiomatic. Better practice is to document them with style: form and explode: true, and clarify in the description. Parameters like only[BASE][] would be better modeled using structured query object modeling or clearly defined array fields.

A general problem throughout is the overloading of description and summary fields: summary is crammed with multiple use cases instead of a brief 1-line summary, and description includes tons of raw HTML - valid per spec, but not best practice. These fields are intended for humans (e.g. devs using Swagger UI), so readability is key.

Interestingly, some parts of the specs suffer from the inverse of the above: a 200 response with just description: "" and no schema or example is valid, but under-documented.

Ultimately, as it stands, the Open API specs are serviceable but unworkable for any of the more exciting use cases that the format can provide. Anyone interested in leveraging the specs offered is forced to sanitise or post-process them - e.g. trimming HTML, rewriting parameter names, and simplifying operation summaries/IDs.