Properly adding new endpoints

[tejashah88]

One of the issues that I can see while going forward is how to future-proof this library when new endpoints are being added. Currently we have the ability to make custom calls but that won't be enough as Amazon keeps on adding new endpoints.

One idea I have so far is an "API coverage" tool that scrapes the Alexa docs for request patterns and compares it to the internal library code and finally generates a table of endpoints that are not implemented yet. I've experimented with this in the node-meraki-dashboard library and aside from a few problems, it turned out to be quite successful.

The major problems as it seems is that:

1. The tool is highly dependent on the fact that the formatting of the Alexa docs will not change.
2. The library's code is a lot more complex and trying to analyze it directly would make more trouble than it's worth.
3. It's hard to reliably test the tool itself, due to the above problems.

These problems could make the tool quite brittle, but it would help in automating the process of checking for new endpoints every once in a while and manually adding them periodically.

[marcelobern]

@tejashah88 I was thinking about this one and in my opinion the ideal solution would be to use an API discovery service and then use a Swagger (or similar) based approach for the API implementation (I think we brushed over this Swagger piece in our issue #1 exchange).

While I found this Google API discovery service I have not been able to locate a similar service for AWS.

I am not necessarily a fan of the scrapping approach for the reasons you pointed out and I would venture asking AWS about their API discovery service or even a Swagger representation of (at least) SMAPI.

Thoughts?

[tejashah88]

@marcelobern That's a great idea actually. I'll definitely reach out to them and ask about either an openAPI or Swagger spec. Ideally, the spec should define the client library and it's simply a manner of updating the spec as and when needed.

[tejashah88]

I just got an email back and they have no API spec as of now. Looks like we'll be on our own.