[documentation] documentation for policy author API (and others)

[jaimeventura]

Hey,
Is there a page documenting documentation for policy author API (and others)?

If not, is there some info somewhere i could use to help producing such documentation (other than just reading the source code)?

Thanks

[avatarneil]

Hi Jaime, sorry for not getting to this issue till now, I completely missed the notification! We attempted to get the Policy Author API into the OMF a couple years ago, but it got stuck in a bit of a limbo. The markdown spec I'm linking here may not be 100% up-to-date, but should be reasonably close openmobilityfoundation/mobility-data-specification#497. Similarly, if you're looking for the Geography Author spec or Audit spec, I linked those here as well; though again it's worth noting, they may be slightly out of date.

Internally, we haven't actively been using the Policy Author API recently, as we've opted to instead make calls against the Policy Service Client directly -- our stack is almost entirely isomorphic typescript. Using the Policy Author API isn't the only way to write new policies, for example if you had another piece of Javascript or Typescript code running on the same network, you could call the PolicyServiceClient directly, and make an RPC request to the Policy Service to create/edit/publish a Policy (ensuring that POLICY_SERVICE_RPC_HOST and POLICY_SERVICE_RPC_PORT environment variables are set).

For some packages, we have OpenAPI specs alongside them, for example the [Transaction API] and [Compliance API] each have a spec.yaml file within the spec folder of their respective packages.

Are there any other APIs that aren't currently documented that you'd like to see OpenAPI specs for? I know having them for everything is the ideal scenario, but if you could pick a handful which are most important to you I can prioritize them accordingly!

[jaimeventura]

Hey,
thank you so much for this valuable info.

About policy author API being adopted into MDS, as an interested user, i can ask OMF to look at this.

Regarding the components having openAPI, this is just great, although it lack some context information for the basic user (for instance, how does it work, whats a compliance snapshot,...? ... I guess im asking too much :P )

We understood one could use typescript's RPC (you're calling component-service in component-api via RPC), but we're not using typescript, so the APIs are the what we need (we'll ping you if we find any troubles using it).

Again, thank you so much for this. We were reading the code to find the operations available. This will surely ease our task (we're developing a frontend app for our city services).

Jaime

[avatarneil]

@jaimeventura You're definitely right that while an OpenAPI spec helps, it's not the end-all-be-all without good descriptions of the endpoints/entities! I'll look into adding some additional contextual information, you're definitely not asking for too much :)

[avatarneil]

@jaimeventura I can't seem to tag you on the PR directly (need to look into why that's happening), but I made a small PR to add some more descriptions to the Compliance API spec. Please review, if you have any other questions I'd be happy to answer them and update the PR accordingly! #870

[jaimeventura]

Hey @avatarneil
Thank you so much fo the effort.
I missed your comment and i can see the changes were merged.