Add alpha API documentation

api/README.md

@@ -0,0 +1,12 @@
+# DRAFT #
+# OpenShift v3 REST API (Alpha) 
+
+## Viewing the documentation ##
+Clone this repository and open oov3.html locally on your browser
+
+## Generating the API document
+Use [raml2html](https://www.npmjs.org/package/raml2html):
+```
+$ raml2html -i oov3.raml -o oov3.html
+```
+For additional documentation on raml go to [http://raml.org/](http://raml.org/)

api/doc/controller-schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A replicationController resource. A replicationController helps to create and manage a set of pods. It acts as a factory to create new pods based on a template. It ensures that there are a specific number of pods running. If fewer pods are running than `replicas` then the needed pods are generated using `podTemplate`. If more pods are running than `replicas`, then excess pods are deleted.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the replicationController",
+      "properties": {
+        "replicas": {
+          "type": "number",
+          "required": false,
+          "description": "Number of pods desired in the set"
+        },
+        "replicaSelector": {
+          "type": "object",
+          "required": false,
+          "description": "Required labels used to identify pods in the set"
+        },
+        "podTemplate": {
+          "type": "object",
+          "required": false,
+          "description": "Template from which to create new pods, as necessary. Identical to pod schema."
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}

api/doc/image-streams.md

@@ -0,0 +1,9 @@
+An image stream is a collection of images that share the same metadata. It contains multiple
+versions of an image as it evolves over time with new builds of the codebase. 
+
+An image stream is one of the sources of image metadata. Metadata for an image can come from one of three places:
+* The original image binary as specified by the Dockerfile - this includes environment variables, command to execute, ports exposed, etc.
+* The image definition in the OpenShift environment. This can be used to override metadata from the Dockerfile
+* The image stream which overrides individual image metadata.
+
+Some images can be used as services while others can be used as single execution jobs.

api/doc/manifest-schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema",
+  "type": "object",
+  "description": "Manifest describing group of [Docker containers](http://docker.io); also used by [Google Cloud Platform's container-vm images](https://developers.google.com/compute/docs/containers).",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "The version of the manifest.",
+      "enum": [
+        "v1beta1"
+      ]
+    },
+    "containers": {
+      "type": "array",
+      "description": "The list of containers to launch.",
+      "items": {
+        "type": "object",
+        "required": [
+          "image"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description" : "A symbolic name used to create and track the container. Must be an RFC1035 compatible value (a single segment of a DNS name). All containers must have unique names."
+          }, 
+          "image": {
+            "type": "string",
+            "description" : "The container image to run."
+          }, 
+          "command": {
+            "type": "array",
+            "description" : "The command line to run. If this is omitted, the container is assumed to have a command embedded in it.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "workingDir": {
+            "type": "string",
+            "description" : "The initial working directory for the command. Default is the container’s embedded working directory or else the Docker default."
+          }, 
+          "volumeMounts": {
+            "type": "array",
+            "description" : "Data volumes to expose into the container.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description" : "The name of the volume to mount. This must match the name of a volume defined in volumes[]."
+                }, 
+                "mountPath": {
+                  "type": "string",
+                  "description" : "The path at which to mount the volume inside the container. This must be an absolute path and no longer than 512 characters."
+                }, 
+                "readOnly": {
+                  "type": "boolean",
+                  "description" : "Whether this volume should be read-only. Default is false (read-write)."
+                }
+              }
+            }
+          },
+          "ports": {
+            "type": "array",
+            "description" : "Ports to expose from the container. All of these are exposed out through the public interface of the VM.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description" : "A symbolic name used to create and track the port. Must be an RFC1035 compatible value (a single segment of a DNS name)."
+                },
+                "containerPort": {
+                  "type": "integer",
+                  "description" : "The port on which the container is listening."
+                }, 
+                "hostPort": {
+                  "type": "integer",
+                  "description" : "The port on the host which maps to the containerPort. Default is auto-allocated."
+                }, 
+                "protocol": {
+                  "type": "string",
+                  "description" : "The protocol for this port. Valid options are TCP and UDP. Default is TCP."
+                }
+              }
+            }
+          },
+          "env": {
+            "type": "array",
+            "description" : "Environment variables to set before the container runs.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description" : "The name of the environment variable."
+                }, 
+                "value": {
+                  "type": "string",
+                  "description" : "The value of the environment variable."
+                }
+              }
+            }
+          }
+        }
+      }
+    }, 
+    "volumes": {
+      "type": "array", 
+      "description" : "A list of volumes to share between containers.",
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description" : "The name of the volume. Must be an RFC1035 compatible value (a single segment of a DNS name). All volumes must have unique names. These are referenced by `containers[].volumeMounts[].name`.",
+            "pattern": "^[a-z]([-a-z0-9]*[a-z0-9])*"
+          }
+        }
+      }
+    }
+  }
+}

api/doc/overview.md

@@ -0,0 +1,10 @@
+The 3.x model attempts to expose underlying Docker and Google models as
+accurately as possible, with a focus on easy composition of applications
+by a developer (install Ruby, push code, add MySQL). Unlike 2.x, more
+flexibility of configuration is exposed after creation in all aspects
+of the model. Terminology is still being weighed, but the concept of an
+application as a separate object is being removed in favor of more flexible
+composition of "services" - allowing two web containers to reuse a DB,
+or expose a DB directly to the edge of the network.
+The existing API will continue to be supported through 3.x,
+with concepts mapped as closely as possible to the new model.

api/doc/pod-schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "Pod resource. A pod corresponds to a co-located group of [Docker containers](http://docker.io).",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the pod",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false,
+          "description": "Manifest describing group of [Docker containers](http://docker.io); compatible with format used by [Google Cloud Platform's container-vm images](https://developers.google.com/compute/docs/containers)"
+        },
+        "status": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "host": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "info": {
+          "type": "object",
+          "required": false,
+          "description": ""
+        }
+      }
+    },
+    "currentState": {
+      "type": "object",
+      "required": false,
+      "description": "The current configuration and status of the pod. Fields in common with desiredState have the same meaning.",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false
+        },
+        "status": {
+          "type": "string",
+          "required": false
+        },
+        "host": {
+          "type": "string",
+          "required": false
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false
+        },
+        "info": {
+          "type": "object",
+          "required": false
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}

api/doc/projects.md

@@ -0,0 +1,3 @@
+Projects are a similar concept to v2 domains. A project is a grouping of services with shared
+access control and resource limits. Applications can be assembled from services in a project
+by linking them together via service endpoints.

api/doc/service-schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A service resource.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    },
+    "port": {
+      "type": "number",
+      "required": false
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    },
+    "selector": {
+      "type": "object",
+      "required": false
+    }
+  }
+}

api/examples/alias.json

@@ -0,0 +1,16 @@
+{
+  "data":
+  {
+    "id": "53c4249f076573c0f4000001",
+    "suffix": "dev.rhcloud.com",
+    "name": "mydomain",
+    "members": [
+       {
+         "login": "adminuser",
+         "role": "admin",
+         "type": "user",
+         "owner": true
+       }
+    ]
+  }
+}

api/examples/aliases.json

@@ -0,0 +1,11 @@
+{
+  "list":
+  [
+    {
+    "id": "myalias",
+    "ssl_certificate": "-----BEGIN CERTIFICATE-----\nMIIDoDCCAogCCQDzF8AJCHnrbjANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC\nVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJl\nZGhhdDESMBAGA1UECwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAm\nBgkqhkiG9w0BCQEWGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wHhcNMTMwMjE5\nMjExMTQ4WhcNMTQwMjE5MjExMTQ4WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM\nAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJlZGhhdDESMBAGA1UE\nCwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAmBgkqhkiG9w0BCQEW\nGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDAEbH4MCi3iIDP1HS+/Xwu8SjdSc5WJX6htV7hJpmFZ8HohV/8\nba0v6aM9IJIIt+sIe2J62t/9G3leOdIHBxeACN4fV2l/iA/fvxvlnFKeD7sHm9Oc\nYj1H6YYJ57sIOf/oLDpJl6l3Rw8VC3+3W0/lzlVpA8qt7fpkiW7XQJCPplUSrdVC\n3okQ2T5NAod5+wVIOqELgE5bLX1LRs5VPsjytHkJ7rKXs55FHR3kpsoImn5xD0Ky\n6lRn8cIMolQoyN5HIGr8f5P+07hrHibve8jje/DKTssb5yEUAEmh6iGHQsRAnsUW\nQoIEUOLqQCu9re2No4G52Kl2xQIjyJF7rCfxAgMBAAEwDQYJKoZIhvcNAQEFBQAD\nggEBAGHrya/ZkiAje2kHsOajXMlO2+y1iLfUDcRLuEWpUa8sI5EM4YtemQrsupFp\n8lVYG5C4Vh8476oF9t8Wex5eH3ocwbSvPIUqE07hdmrubiMq4wxFVRYq7g9lHAnx\nl+bABuN/orbAcPcGAGg7AkXVoAc3Fza/ZcgMcw7NOtDTEss70V9OdgCfQUJL0KdO\nhCO8bQ1EaEiq6zEh8RpZe8mu+f/GYATX1I+eJUc6F6cn83oJjE9bqAVzk7TzTHeK\nEBKN50C14wWtXeG7n2+ugaVO+0xnvHeUrQBLHSRyOHqxXrQQ5XmzcaBiyI0f2IQM\nHst1BVXyX0n/L/ZoYYsv5juJmDo=\n-----END CERTIFICATE-----",
+    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAwBGx+DAot4iAz9R0vv18LvEo3UnOViV+obVe4SaZhWfB6IVf\n/G2tL+mjPSCSCLfrCHtietrf/Rt5XjnSBwcXgAjeH1dpf4gP378b5ZxSng+7B5vT\nnGI9R+mGCee7CDn/6Cw6SZepd0cPFQt/t1tP5c5VaQPKre36ZIlu10CQj6ZVEq3V\nQt6JENk+TQKHefsFSDqhC4BOWy19S0bOVT7I8rR5Ce6yl7OeRR0d5KbKCJp+cQ9C\nsupUZ/HCDKJUKMjeRyBq/H+T/tO4ax4m73vI43vwyk7LG+chFABJoeohh0LEQJ7F\nFkKCBFDi6kArva3tjaOBudipdsUCI8iRe6wn8QIDAQABAoIBAG/on4JVRRQSw8LU\nLiWt+jI7ryyoOUH2XL8JtzuGSwLwvomlVJT2rmbxQXx3Qr8zsgziHzIn30RRQrkF\nBXu0xRuDjzBBtSVqeJ1Mc4uoNncEAVxgjb5bewswZDnXPCGB8bosMtX4OPRXgdEo\nPwTtfjMOsrMaU3hd5Xu4m81tQA2BvwOlx8aYDyH0jeTnervc5uRGbeTBQG4Bu40E\nrWNmXvgNq2EzTAwbbN6Ma97gw9KgXnM4Nlh29Fxb5TBeUU9lkzuTZAZIDXKIm7AG\nUwMbj/A038yAumYQtThTE/3e4W3rn7F2Vko900bC4aAC1KQOAzjIeQqzqkVxWTWq\n4SUFQAECgYEA/ODwifOTuI6hdZK6JRgc4wp6Rc0fkqHuxLzABXoIGuSVlWyimqIN\nZySAkpo5EW6DNraRJxNCOBmWeGPEhHGrea+JPiPEwCK0F7SxvSmg3jzNzw3Es31T\necET7eDwuSOY9v4XDzLyiXXkEUUReD7Ng2hEYL+HaQrl5jWj4lxgq/ECgYEAwnCb\nKrz7FwX8AqtFAEi6uUrc12k1xYKQfrwSxbfdK2vBBUpgB71Iq/fqP+1BittEljDG\n8f4jEtMBFfEPhLzGIHaI3UiHUHXS4GetA77TRgR8lnKKpj1FcMIY2iKU479707O5\nQ08pgWRUDQ8BVg2ePgbo5QjLMc/rv7UF3AHvPAECgYB/auAIwqDGN6gHU/1TP4ke\npWLi1O55tfpXSzv+BnUbB96PQgPUop7aP7xBIlBrBiI7aVZOOBf/qHT3CF421geu\n8tHWa7NxlIrl/vgn9lfGYyDYmXlpb1amXLEsBVGGF/e1TGZWFDe9J5fZU9HvosVu\n1xTNIvSZ6xHYI2MGZcGYIQKBgEYeebaV5C7PV6xWu1F46O19U9rS9DM//H/XryVi\nQv4vo7IWuj7QQe7SPsXC98ntfPR0rqoCLf/R3ChfgGsr8H8wf/bc+v9HHj8S5E/f\ndy1e3Nccg2ej3PDm7jNsGSlwmmUkAQGHAL7KwYzcBm1UB+bycvZ1j2FtS+UckPpg\nMDgBAoGALD8PkxHb4U4DtbNFSYRrUdvS9heav/yph3lTMfifNkOir36io6v8RPgb\nD2bHKKZgmYlTgJrxD45Er9agC5jclJO35QRU/OfGf3GcnABkBI7vlvUKADAo65Sq\nweZkdJnbrIadcvLOHOzkKC9m+rxFTC9VoN1dwK2zwYvUXfa1VJA=\n-----END RSA PRIVATE KEY-----",
+    "pass_phrase": "abcd"
+    }
+  ]
+}

api/examples/build-results.json

@@ -0,0 +1,19 @@
+{
+  "list":
+  [
+    {
+      "id": "53c4249f076573c0f4000001",
+      "startTime": "2014-07-15T03:58:40Z",
+      "endTime": "2014-07-15T03:59:40Z",
+      "result": "SUCCESS",
+      "logs": "http://url/to/build/logs"
+    },
+    {
+      "id": "53c4249f076573c0f4000002",
+      "startTime": "2014-07-15T04:58:40Z",
+      "endTime": "2014-07-15T04:59:40Z",
+      "result": "FAILURE",
+      "logs": "http://url/to/build/logs"
+    }
+  ]
+}