You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 #38
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.
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:
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...
Automatically generate the OpenAPI for existing deployed services
Standardize what a planner API looks like (already kind of done with the planner template manifest)
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?
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
andproblem
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 ofstatus: PENDING
it is a string/URL, and in context ofstatus: ok
, it is a structure. I recommend putting the URL to a distinctly different element outside of theresult
field. This is submitted as a separate issue #38I 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 thecategorical
choicevalue
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
The text was updated successfully, but these errors were encountered: