#%RAML 0.8
baseUri: http://server/api/{version}
title: Kubernetes
version: v1beta1
mediaType: application/json
documentation:
 - title: Overview
   content: |
     The Kubernetes API currently manages 3 main resources: `pods`,
     `replicationControllers`, and `services`. Pods correspond to
     colocated groups of [Docker containers](http://docker.io) with
     shared volumes, as supported by [Google Cloud Platform's
     container-vm
     images](https://developers.google.com/compute/docs/containers).
     Singleton pods can be created directly via the `/pods`
     endpoint. Sets of pods may created, maintained, and scaled using
     replicationControllers.  Services create load-balanced targets
     for sets of pods.

 - title: Resource identifiers
   content: |
     Each resource has a string `id` and list of key-value
     `labels`. The `id` is generated by the system and is guaranteed
     to be unique in space and time across all resources.  `labels`
     is a map of string (key) to string (value). Each resource may
     have at most one label with a particular key. Individual labels
     are used to specify identifying metadata that can be used to
     define sets of resources by specifying required labels. Examples
     of typical pod label keys include `stage`, `service`, `name`,
     `tier`, `partition`, and `track`, but you are free to develop
     your own conventions.

 - title: Creation semantics
   content: |
     Creation is currently not idempotent. We plan to add a
     modification token to each resource. A unique value for the token
     should be provided by the user during creation. If the user
     specifies a duplicate token at creation time, the system should
     return an error with a pointer to the exiting resource with that
     token. In this way a user can deterministically recover from a
     dropped connection during a resource creation request.

 - title: Update semantics
   content: |
     Custom verbs are minimized and are used only for 'edge triggered'
     actions such as a reboot. Resource descriptions are generally set
     up with `desiredState` for the user provided parameters and
     `currentState` for the actual system state. While consistent
     terminology is used across these two stanzas they do not match
     member for member.

     When a new version of a resource is PUT the `desiredState` is
     updated and available immediately. Over time the system will work
     to bring the `currentState` into line with the `desiredState`. The
     system will drive toward the most recent `desiredState` regardless
     of previous versions of that stanza. In other words, if a value
     is changed from 2 to 5 in one PUT and then back down to 3 in
     another PUT the system isn't required to 'touch base' at 5 before
     making 3 the `currentState`.

     When doing an update, we assume that the entire `desiredState`
     stanza is specified. If a field is omitted it is assumed that the
     user is looking to delete that field. It is viable for a user to
     GET the resource, modify what they like in the `desiredState` or
     labels stanzas and then PUT it back. If the `currentState` is
     included in the PUT it will be silently ignored.

     While currently unspecified, it is intended that concurrent
     modification should be accomplished with optimistic locking of
     resources. We plan to add a modification token to each resource. If
     this is included with the PUT operation the system will verify
     that there haven't been other successful mutations to the
     resource during a read/modify/write cycle. The correct client
     action at this point is to GET the resource again, apply the
     changes afresh and try submitting again.

     Note that updates currently only work for replicationControllers
     and services, but not for pods. Label updates have not yet been
     implemented, either.

/pods:
  get:
    description: List all pods on this cluster
    responses:
      200:
        body:
          example: !include examples/pod-list.json
  post:
    description: Create a new pod. currentState is ignored if present.
    body:
      schema: !include doc/pod-schema.json
      example: !include examples/pod.json
  
  /{podId}:
    get:
      description: Get a specific pod
      responses:
        200:
          body:
            example: !include examples/pod.json
    put:
      description: Update a pod
      body:
        schema: !include doc/pod-schema.json
        example: !include examples/pod.json
    delete:
      description: Delete a specific pod
      responses:
        200:
          body:
            example: |
              { 
                "success": true
              }

/replicationControllers:
  get:
    description: List all replicationControllers on this cluster
    responses:
      200:
        body:
          example: !include examples/controller-list.json
  post:
    description: Create a new controller. currentState is ignored if present.
    body:
      schema: !include doc/controller-schema.json
      example: !include examples/controller.json
  
  /{controllerId}:
    get:
      description: Get a specific controller
      responses:
        200:
          body:
            example: !include examples/controller.json
    put:
      description: Update a controller
      body:
        schema: !include doc/controller-schema.json
        example: !include examples/controller.json
    delete:
      description: Delete a specific controller
      responses:
        200:
          body:
            example: |
              { 
                "success": true
              }

/services:
  get:
    description: List all services on this cluster
    responses:
      200:
        body:
          example: !include examples/service-list.json
  post:
    description: Create a new service
    body:
      schema: !include doc/service-schema.json
      example: !include examples/service.json
  
  /{serviceId}:
    get:
      description: Get a specific service
      responses:
        200:
          body:
            example: !include examples/service.json
    put:
      description: Update a service
      body:
        schema: !include doc/service-schema.json
        example: !include examples/service.json
    delete:
      description: Delete a specific service
      responses:
        200:
          body:
            example: |
              { 
                "success": true
              }