API - Assumptions Probably Incorrect

addendum.markdown

Here are some resources that I found helpful and found inspiration from when I was writing the talk.

• How To Design A good API and Why It Matters by Joshua Bloch
• Albert Einstein Quotes from Brainy Quote
• The Art of Unix Programming by Eric Steven Raymond

api.markdown

API

METHOD /service/provider/collection/[identity]

Perhaps its better/more consistent to swap service/provider. This better maps to the general case, whereas the other way maps mostly just to the shared services.

METHOD /provider/service/collection/[identity]

What about one off actions? Perhaps:

METHOD /provider/service/collection/[identity]/[action]

• get all servers => GET /aws/compute/servers
• create a c1-medium server => POST /aws/compute/servers?attributes={'flavor':'c1-medium'}
• lookup server by identity => GET /aws/compute/servers/i-12345678
• destroy server => DELETE /aws/compute/servers/i-12345678

Probably needs a lot of work, but doesn't seem terrible.

cli.markdown

CLI

fogcli service provider collection action options

First attempt:

• (explicit) get all servers => fogcli compute aws servers all
• (implicit) get all servers => fogcli compute aws servers
• create a c1-medium server => fogcli compute aws servers create flavor:c1-medium
• lookup server by identity => fogcli compute aws servers get i-12345678
• destroy server => fogcli compute aws servers destroy ?

Destroy is a problem, historically it has always just worked on a single resource that you already have a reference to. This lead to adding a destroy method to collections, which takes an id and we get what you would expect:

Next attempt:

• (explicit) get all servers => fogcli compute aws servers all
• (implicit) get all servers => fogcli compute aws servers
• create a c1-medium server => fogcli compute aws servers create flavor:c1-medium
• lookup server by identity => fogcli compute aws servers get i-12345678
• destroy server => fogcli compute aws servers destroy i-12345678

This seems fairly workable, though perhaps the compute/aws arguments should be flipped to better match in the general case (currently this maps well to shared things [cdn, compute, dns, storage] but not to singleton things). Lets try:

fogcli provider service collection action options

Finalish attempt:

• (explicit) get all servers => fogcli aws compute servers all
• (implicit) get all servers => fogcli aws compute servers
• create a c1-medium server => fogcli aws compute servers create flavor:c1-medium
• lookup server by identity => fogcli aws compute servers get i-12345678
• destroy server => fogcli aws compute servers destroy i-12345678

Possible improvements:

Could probably use some more cleanup, its quite wordy for instance. This seems workable, but it might be nice to instead use something where you could set an option and do multiple operations, ie something like:

• set aws compute => fogcli use aws compute
• (explicit) get all servers => fogcli servers all
• (implicit) get all servers => fogcli servers
• create a c1-medium server => fogcli servers create flavor:c1-medium
• lookup server by identity => fogcli servers get i-12345678
• destroy server => fogcli servers destroy i-12345678

This is a lot quicker to type, but the implicitness perhaps makes it harder to read through and reason about. I remain on the fence on this so far (which I can do since I'm not quite ready to implement it yet anyway).