Some thoughts regarding the ALPS descriptors and its OAS output

[nnworkspace]

Hi,

the artifacts I'm refering to are:

• input: https://github.com/mamund/alps-unified/blob/main/samples/company-ext-alps.yaml
• output: https://github.com/mamund/alps-unified/blob/main/samples/company-oas.yaml

Action-vocabularies such as "listCompanies", "filterCompanies", "readCompany" etc. are fine as is at a conceptual level. Though I'd like to have a way to describe which parameters are mandatory and which are optional.

The oas output, however, does not quite look like best practices in the HTTP RESTful world. In the output oas file:

1. It is almost a convention now to use GET "/companies" for the conceptual action "listCompanies".
2. For the action "filterCompanies", in the alps file, there are four query parameters. But in the output file, no query parameters are specified. In addition, it is better to use GET "/companies?legalName=blah&addressCountry=blah&...." instead of GET "filterCompanies?......"
3. Similar comments for the create/update/delete actions.

A very concise book which explains the most current best practices can be found here:
https://cloud.google.com/files/apigee/apigee-web-api-design-the-missing-link-ebook.pdf

[mamund]

@nnworkspace

thanks for the feedback. love to see your thoughts on this.

1. ALPS is not a definition format like OAS, RAML, AsyncAPI, proto3, gQL, or other interface definition languages (IDLs). it is a much more abstract way to describe an interface. when @leonardr and i were first creating it, we were trying to create something that describes the problem space instead of the solution space. that's kind of esoteric and not meant as a "hand-wave".

2. I totally agree that the OAS output is not within recommended standards. I got some of the same feedback on the lack of common practice for the protobuf version from @corntoole (who is spot on, as well).

i am very much looking for PRs on this to make it better. there are challenges here, but i don't think they're insurmountable.

finally, there is a mailing list where we can continue to talk about ALPS (https://groups.google.com/g/alps-io/) and we have open office hours every thursday at 14:30 UTC (not GMT) time. it would be great to connect and see where we can work together to make this all better.

-- @mamund