Update docs (#212)

Author: ospillinger

docs/apis/apis.md

@@ -1,13 +1,13 @@
 # APIs
 
-Serve models at scale and use them to build smarter applications.
+Serve models at scale.
 
 ## Config
 
 ```yaml
 - kind: api
   name: <string>  # API name (required)
-  model: <string>  # path to a zipped model dir (e.g. s3://my-bucket/model.zip)
+  model: <string>  # path to an exported model (e.g. s3://my-bucket/model.zip)
   model_format: <string>  # model format, must be "tensorflow" or "onnx"
   request_handler: <string>  # path to the request handler implementation file, relative to the cortex root
   compute:
@@ -40,17 +40,3 @@ See [packaging models](packaging-models.md) for how to create the zipped model.
 Request handlers are used to decouple the interface of an API endpoint from its model. A `pre_inference` request handler can be used to modify request payloads before they are sent to the model. A `post_inference` request handler can be used to modify model predictions in the server before they are sent to the client.
 
 See [request handlers](request-handlers.md) for a detailed guide.
-
-## Integration
-
-APIs can be integrated into other applications or services via their JSON endpoints. The endpoint for any API follows the following format: {apis_endpoint}/{deployment_name}/{api_name}.
-
-The fields in the request payload for a particular API should match the raw columns that were used to train the model that it is serving. Cortex automatically applies the same transformers that were used at training time when responding to prediction requests.
-
-## Horizontal Scalability
-
-APIs can be configured using `replicas` in the `compute` field. Replicas can be used to change the amount of computing resources allocated to service prediction requests for a particular API. APIs that have low request volumes should have a small number of replicas while APIs that handle large request volumes should have more replicas.
-
-## Rolling Updates
-
-When the model that an API is serving gets updated, Cortex will update the API with the new model without any downtime.

docs/apis/compute.md

@@ -1,11 +1,11 @@
 # Compute
 
-Compute resource requests in Cortex follow the syntax and meaning of [compute resources in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/).
+Compute resource requests in Cortex follow the syntax and meaning of [compute resources in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container).
 
 For example:
 
 ```yaml
-- kind: model
+- kind: api
   ...
   compute:
     cpu: "2"

docs/apis/deployment.md

@@ -0,0 +1,17 @@
+# Deployments
+
+Deployments are used to group a set of resources that can be deployed as a single unit. It must be defined in every Cortex directory in a top-level `cortex.yaml` file.
+
+## Config
+
+```yaml
+- kind: deployment
+  name: <string>  # deployment name (required)
+```
+
+## Example
+
+```yaml
+- kind: deployment
+  name: my_deployment
+```

docs/apis/deployments.md

@@ -14,20 +14,3 @@
 | upstream error          | Resource was not created due to an error in one of its dependencies |
 | upstream termination    | Resource was not created because one of its dependencies was terminated |
 | compute unavailable     | Resource's workload could not start due to insufficient memory, CPU, or GPU in the cluster |
-
-## API statuses
-
-| Status               | Meaning |
-|----------------------|---|
-| ready                | API is deployed and ready to serve prediction requests |
-| pending              | API is waiting for another resource to be ready, or is initializing |
-| updating             | API is performing a rolling update |
-| update pending       | API will be updated when the new model is ready; a previous version of this API is ready |
-| stopping             | API is stopping |
-| stopped              | API is stopped |
-| error                | API was not created due to an error; run `cortex logs -v <name>` to view the logs |
-| skipped              | API was not created due to an error in another resource |
-| update skipped       | API was not updated due to an error in another resource; a previous version of this API is ready |
-| upstream error       | API was not created due to an error in one of its dependencies; a previous version of this API may be ready |
-| upstream termination | API was not created because one of its dependencies was terminated; a previous version of this API may be ready |
-| compute unavailable  | API could not start due to insufficient memory, CPU, or GPU in the cluster; some replicas may be ready |