The APIs for the Sun Cloud: General Discussion: Make API a bit more self-documenting

The APIs for the Sun Cloud was started in February 2009, is owned by russcastronovo, and has 233 members.

» Join This Project

Make API a bit more self-documenting

» Back to forum topics

2 posts

Replies: 1 - Last Post: January 10, 2010 04:10
by: hedge_hog

« Older Topic » Newer Topic

showing 1 - 2 of 2

Tim Bray

Posted: December 17, 2009 00:11 by Tim Bray

» Permalink

I'm hearing from API implementors that they have a lot of information that would be useful
to app developers and they'd like to be able to deliver it through the API. Here's a
proposal to:

Add a new Instructions resource model, which is a hash whose keys are HTTP verbs like PUT, POST, and DELETE, and the values are human-readable strings with instructions for developers.
Add an optional instructions field to the VDC, Cluster, VM, and VNet resource models, the value being a URI that may be used to retrieve instructions; usually relevant to the resource type generally, but the potential exists to provide instance-specific help.

Instructions [application/vnd.com.sun.cloud.Instructions+json]

An instructions represents instructions as to the HTTP requests that can be applied
to a particular resource. It is a hash whose keys may include GET, HEAD,
POST, PUT, and DELETE, and whose values are plain-text
human-readable explanations aimed at developers who are considering applying the
indicated request to the resource.

Example

Consider a VM which is serving as an application-tier machine; dereferencing its instructions field might yield the following:

{
  "POST" : "This machine is running application code and should not be exposed to the Internet; do not attach a Public IP address to it."
}

hedge_hog

Posted: January 10, 2010 04:10 by hedge_hog

» Permalink

While it is early days on my journey into this API... the instructions field does seem to be useful.

This brings up an idea related to my earlier post: how do I tell vwhat version of the API I'm reading? More importantly is it different from what I was reading 3 weeks ago? If it is different, exactly how?

I had in mind a similar description field of each element of the SCA, which could be web querable... but that doesn't work from kenai's persective.

So I was browsing the description thinking, OK I can just cut-paste some of this description into the docs, when I though why can't I just write a script to traverse and pull out Sun's descriptions, instead of manually doing it... every time the API description gets tweaked? This would also solve the API version issue, I do appreciate Kenai can't host such a solution as a web service. But it could be done using std file system hierachy/layout, store that in git/github and just tag versions, then I can pull down the version I want, and roll forward. It would be even be possible to build some of the wiki from this. Also if this lives on github you'll be able to see at a glance (from the network) people's forks for corrections or changes?

Again, am I totally nuts thinking like this?

Replies: 1 - Last Post: January 10, 2010 04:10
by: hedge_hog

« Older Topic » Newer Topic