gistfile1.mkd

SteamCannon API Notes and Questions

These are some notes and questions I've come up with while working on the SteamCannon API.

Collections - list of links or inlined objects?

For example, when accessing the list of deployments for an environment, the response could be either

<deployments href='http://localhost:8080/environments/1/deployments'>
  <deployment href='http://localhost:8080/environments/1/deployments/1'>
    <environment href='http://localhost:8080/environments/1' rel='environment'></environment>
    <!-- TODO: How to deal with versions? -->
    <!-- It's possible to delete the deployment's artifact. We don't want to barf if one isn't there -->
    <artifact href='http://localhost:8080/artifacts/1'></artifact>
    <name>weld-jsf-permalink-1.1.0.Beta1</name>
    <current_state>undeployed</current_state>
    <datasource></datasource>
    <actions>
      <!-- TODO: should we allow deployment here? -->
    </actions>
  </deployment>
  <deployment href='http://localhost:8080/environments/1/deployments/2'>
    <environment href='http://localhost:8080/environments/1' rel='environment'></environment>
    <!-- TODO: How to deal with versions? -->
    <!-- It's possible to delete the deployment's artifact. We don't want to barf if one isn't there -->
    <artifact href='http://localhost:8080/artifacts/1'></artifact>
    <name>weld-jsf-permalink-1.1.0.Beta1</name>
    <current_state>deployed</current_state>
    <datasource></datasource>
    <actions>
      <!-- TODO: current routes assume DELETE of deployment (via HTTP verb), but we probably want POST -->
      <link href='http://localhost:8080/environments/1/deployments/2' rel='undeploy' />
    </actions>
  </deployment>
</deployments>

Or this:

<deployments href='http://localhost:8080/environments/1/deployments'>
  <deployment href='http://localhost:8080/environments/1/deployments/1'></deployment>
  <deployment href='http://localhost:8080/environments/1/deployments/2'></deployment>
</deployments>

We are not currently consistent. Environments are returned as a list of links, but everything else is inlined.

{{ I like showing one level of objects, with the second level being a list of urls. So a list of environments includes the full envinronment records, but each environment record just has a list of instance urls instead of instance records (I know environment instances is a dc endpoint, so acts a bit differently - I'm just using it as an example here). - Toby }}

Actions for Deployments

I've modeled the actions available for deployments on the DeltaCloud API. All actions should be a POST. Do we just add a method=delete parameter to the undeploy action?
{{ Will the action be named 'undeploy' or 'destroy'? The way we do it now (via the UI) is a bit odd - you use #destroy in the controller to undeploy, and not really destroy (or are we actually doing the destroy asynchronously?). - Toby }}

Can actions that are not deployed be redeployed? For example, it's possible that a deployment failed. At the moment, these appear as deployments in a listing for an environment with a current_state of undeployed. Should we even show these? {{ Maybe we list these for informational purposes, but with no actions. But then they hang around forever. Do we need a destroy action on deployments? That would mean that undeploy would need it's own url and controller method. - Toby }}

Artifact Versions

• How do we deal with artifact versions?

• Can a client create a new Artifact by posting data via the API? {{ I'd say yes - but w/o the first artifact_version - that has to be created separately - Toby }}

• Can a client create a new ArtifactVersion by posting to the API? {{ Hmm. Maybe? it requires posting a possibly quite large blob to the api, but that same blob has to go over the wire if they use the webui. - Toby }}

• How do we expose a deploy action since it requires an environment ID? {{ I think we covered this on irc, right? The id has to be given as a param. - Toby }}

• Can an Artifact or ArtifactVersion be deleted if there are currently running deployments? {{ No, I think that should be against the rules - Toby }}