OpenAPI description needed for the service

[jan-dolejsi]

To document (or test, expose and secure) the endpoints, an OpenAPI file should be created. Doing so would expose the weaknesses of the current interface (which one has to discover by trying to use it). For example, the additional arguments are on the same level as the well-known domain and problem arguments, so you cannot say what is mandatory and what is optional. Similarly, you would have tough time documenting the result element, because in context of status: PENDING it is a string/URL, and in context of status: ok, it is a structure. I recommend putting the URL to a distinctly different element outside of the result field. This is submitted as a separate issue https://github.com/AI-Planning/planning-as-a-service/issues/38

I had to capture the structure for my own sanity: Package manifests: https://github.com/jan-dolejsi/pddl-planning-service-client/blob/569c320e7d48812c3cbe04a02b9d4b81962130f6/src/PackagedPlanners.ts#L22 (note the uncertainty about the argument type type: "file" | "int" | "categorical" // is "string" or "boolean" supported? as well as the categorical choice value type - could that be a number? or a boolean?)

Returned payload: https://github.com/jan-dolejsi/pddl-planning-service-client/blob/main/src/PlannerPackagePreviewService.ts#L125

Attached is the OpenAPI for the original /solve interface as well as a public subset the more detailed sync/async /request interface, which is how we expose the planner in our solutions.

openapi_academia.zip

[haz]

This is definitely an important and oddly weird topic. On the one hand, we want to standardize some elements (how to do categorical arguments, for example), but (crucially) the full API for any individual service is left up to the service author. They specify the arguments / return setup as part of a package manifest in the planutils package. Examples:

• kstar
• lama-first

Note that they both refer to a planner template, which just defaults some of the arguments and return setup: https://github.com/AI-Planning/planutils/blob/main/planutils/packages/TEMPLATE/SERVICE_TEMPLATE/planner.json

Not all packages will use this planner template, though any that wants domain and problem as PDDL arguments probably will. An example service will be on-demand problem generators ( https://github.com/AI-Planning/pddl-generators ). That will have completely different arguments and return values.

The messiness and magic of PaaS+planutils stem from the same flexibility -- allowing package manifests to define their own services however they want.

Now all that said, I think your insights bring us to a few key things we could do...

1. Automatically generate the OpenAPI for existing deployed services
2. Standardize what a planner API looks like (already kind of done with the planner template manifest)
3. Standardize the elements that could be used for the API (e.g., the arg types)

How far do you thing the above 3 would go to simplifying/fixing things?