Undocumented DataSource API getOperationBindings() and getOperationBinding() safe to use (How to document own API)?

[Blama]

Hi Isomorphic,

I'm currently developing my REST API. Besides the API functions itself which I whitelist on a per-operationBinding basis (see here), I need a way to show which functions the API actually offers.
My approach is this:

• For every .ds.xml-file: DataSourceManager.get()
  • For every operationBinding check for apiAllowed="true" (my own attribute)
    • If so, output DataSource with all fields (with name, type, length, required) and all API-allowed operationBindings

This should work for me as 1st solution.
The question is now how to get the information needed - Do you suggest using your DataSource-APIs or a XPath approach?
If yours, could you add DataSource.getOperationBindings() and DataSource.getOperationBinding() which I can see in Eclipse to the list of allowed methods and doc it? I'm pretty sure they are safe to use anyway and perhaps also internally use a XPath (?).

Also, is the approach with the .ds.xml-directory file listing as 1st step the suggested one/best practice?

Thank you & Best regards
Blama

[Isomorphic]

We would recommend working directly with your .ds.xml files and extracting information via XPath, which should be very simple. There's no apparent reason to even retrieve live DataSource instances from the DataSourceManager.

While it may seem like getOperationBindings() would be a simple one to expose, in fact there are a lot of details in terms of expected substructures, their types, custom attributes and what to expect for their types, properties that are defaulted and/or transformed, lifecycle of the objects, etc. So it would *both* be a lot of docs *and* we would tied to a bunch of details of the current implementation.

[Blama]

Hi Isomorphic,

OK, I'll do that then. I agree that the DataSourceManager-overhead, how little it may be, is not needed. Same for getOperationBindings(), which are not needed if using XPath.
One day it might also be an advantage to be able to access custom attributes via XPath without needing your support.
So XPath wins. I'll post back the code when I'm finished in case someone else needs it as well.

Best regards
Blama