From 811689f923b1d4c9bdfbcaf081f0b3244b1fe833 Mon Sep 17 00:00:00 2001 From: Pedro Nasser Date: Tue, 27 Dec 2016 16:03:02 -0200 Subject: [PATCH] API definitions and docs update (#457) * fix: using bolt config/header update now overwrites * api definitions and doc updates * merge docs --- docs/README.md | 2 +- docs/apps.md | 35 ---------- docs/definitions.md | 153 ++++++++++++++++++++++++++++++++++++++++++ docs/function-file.md | 3 + docs/routes.md | 21 ------ 5 files changed, 157 insertions(+), 57 deletions(-) delete mode 100644 docs/apps.md create mode 100644 docs/definitions.md delete mode 100644 docs/routes.md diff --git a/docs/README.md b/docs/README.md index 520ee6572..ae801040e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ If you are a developer using IronFunctions through the API, this section is for you. * [Quickstart](https://github.com/iron-io/functions#quickstart) +* [Definitions](definitions.md) * [fn (CLI Tool)](/fn/README.md) * [Writing functions](writing.md) * [Writing Lambda functions](lambda/create.md) @@ -16,7 +17,6 @@ If you are a developer using IronFunctions through the API, this section is for * [API Reference](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/iron-io/functions/master/docs/swagger.yml) * [Hot containers](hot-containers.md) - ## For Operators If you are operating IronFunctions, this section is for you. diff --git a/docs/apps.md b/docs/apps.md deleted file mode 100644 index fdc8b3901..000000000 --- a/docs/apps.md +++ /dev/null @@ -1,35 +0,0 @@ -# Applications - -Applications are the top level object that groups routes together to create an API. - -## App level configuration - -When creating or updating an app, you can pass in a map of config variables. - -`config` is a map of values passed to the route runtime in the form of -environment variables. - -Note: Route level configuration overrides app level configuration. - -```sh -fn apps create --config k1=v1 --config k2=v2 myapp -``` - -Or using a cURL: - -```sh -curl -H "Content-Type: application/json" -X POST -d '{ - "app": { - "name":"myapp-curl", - "config": { - "k1": "v1", - "k2": "v2" - } - } -}' http://localhost:8080/v1/apps -``` - -## Notes - -App names are immutable. When doing `PUT` calls, keep in mind that although you -are able to update an app's configuration set, you cannot really rename it. \ No newline at end of file diff --git a/docs/definitions.md b/docs/definitions.md new file mode 100644 index 000000000..8a63cfb2a --- /dev/null +++ b/docs/definitions.md @@ -0,0 +1,153 @@ +# API Definitions + +# Applications + +Applications are the top level object that groups routes together to create an API. + +### Creating applications + +Using `fn`: + +```sh +fn apps create --config k1=v1 --config k2=v2 myapp +``` + +Or using a cURL: + +```sh +curl -H "Content-Type: application/json" -X POST -d '{ + "app": { + "name":"myapp-curl", + "config": { + "k1": "v1", + "k2": "v2" + } + } +}' http://localhost:8080/v1/apps +``` + +### App Example + +```json +{ + "name": "myapp", + "myconfig": "config" +} +``` + +### Properties + +#### name (string) + +`name` is a property that references an unique app. + +App names are immutable. When updating apps with `PATCH` requests, keep in mind that although you +are able to update an app's configuration set, you cannot really rename it. + +#### config (object) + +`config` is a map of values passed to the route runtime in the form of +environment variables. + +Note: Route level configuration overrides app level configuration. + +## Routes + +### Creating routes + +Using `fn`: + +```sh +fn routes create --config k1=v1 --config k2=v2 myapp /path image +``` + +Or using a cURL: + +```sh +curl -H "Content-Type: application/json" -X POST -d '{ + "app": { + "path": "/path", + "image": "image", + "config": { + "k1": "v1", + "k2": "v2" + } + } +}' http://localhost:8080/v1/apps/myapp/routes +``` + +### Route Example +```json +{ + "path": "/hello", + "image": "iron/hello", + "type": "sync", + "memory": 128, + "config": { + "key": "value", + "key2": "value2", + "keyN": "valueN", + }, + "headers": { + "content-type": [ + "text/plain" + ] + } +} +``` + +### Properties + +#### path (string) + +Represents a unique `route` in the API and is identified by the property `path` and `app`. + +Every `route` belongs to an `app`. + +Note: Route paths are immutable. If you need to change them, the appropriate approach +is to add a new route with the modified path. + +#### image (string) + +`image` is the name or registry URL that references to a valid container image located locally or in a remote registry (if provided any registry address). + +If no registry is provided and image is not available locally the API will try pull it from a default public registry. + +#### type (string) + +Options: `sync` and `async` + +`type` is defines how the function will be executed. If type is `sync` the request will be hold until the result is ready and flushed. + +In `async` functions the request will be ended with a `call_id` and the function will be executed in the background. + +#### memory (number) + +`memory` defines the amount of memory (in megabytes) required to run this function. + +#### config (object of string values) + +`config` is a map of values passed to the route runtime in the form of +environment variables. + +Note: Route level configuration overrides app level configuration. + +#### headers (object of array of string) + +`header` is a set of headers that will be sent in the function execution response. The header value is an array of strings. + +#### format (string) + +`format` defines if the function is running or not in `hot container` mode. + +To define the function execution as `hot container` you set it as one of the following formats: + +- `"http"` + +### 'Hot Container' Only Properties + +This properties are only used if the function is in `hot container` mode + +#### max_concurrency (string) + +This property defines the maximum amount of concurrent hot containers instances the function should have (per IronFunction node). \ No newline at end of file diff --git a/docs/function-file.md b/docs/function-file.md index 9899a5bcc..2d00281e5 100644 --- a/docs/function-file.md +++ b/docs/function-file.md @@ -18,6 +18,9 @@ config: key: value key2: value2 keyN: valueN +headers: + content-type: + - text/plain build: - make - make test diff --git a/docs/routes.md b/docs/routes.md deleted file mode 100644 index 5ba7e619e..000000000 --- a/docs/routes.md +++ /dev/null @@ -1,21 +0,0 @@ -# Routes - -Each application has several functions represented through routes. - -## Route level configuration - -When creating or updating an app, you can pass in a map of config variables. - -`config` is a map of values passed to the route runtime in the form of -environment variables. - -Note: Route level configuration overrides app level configuration. - -```sh -fn routes create --config k1=v1 --config k2=v2 myapp /path image -``` - -## Notes - -Route paths are immutable. If you need to change them, the appropriate approach -is to add a new route with the modified path. \ No newline at end of file