Updated API Docs

(Jim Anderson) #1

As you may know, our “reference” documentation has been hosted on a different server than the rest of our documentation (graph.api.smartthings.com). This poses a few problems for us, namely:

  • Viewing the reference documentation requires a log in. Annoying.
  • Because it’s password-protected, our documentation isn’t indexed by the Google machine.
  • Because it’s on a different server, the ReadTheDocs search doesn’t include the reference documentation. Very inconvenient.
  • It creates unnecessary load on the graph.smartthings.api server (which is also where our IDE is hosted).

To remedy those issues, we are migrating our “reference” documentation into our documentation hosted by ReadTheDocs.

Our initial goals are:

  1. Get the docs off of graph.api.smartthings.
  2. Add clarifications/examples where it’s easy to do so.

This initial roll-out does not include:

  1. Documenting everything that’s not currently documented.
  2. Including examples for every API or capability.

You can find the new API docs here.

The Capabilities Taxonomy has also been moved; you can find it here. This will take some time to fill in details about each capability, but we think we’ve got a good jumping-off point.

We have added redirects from the reference documentation on graph that should go live later today, so old links found here on the forum should still work.

We hope you find this new documentation a useful improvement!

(Jody) #2

Very cool. I like the direction being taken with the capabilities section. Great work @Jim ! Any update on when additional capabilities are being added (if any)?

(Tim Slagle) #3

Nice job @jim! Keep the good stuff rolling my friend!