github.com/iron-io/functions@v0.0.0-20180820112432-d59d7d1c40b2/docs/definitions.md (about)

     1  # API Definitions
     2  
     3  # Applications
     4  
     5  Applications are the top level object that groups routes together to create an API.
     6  
     7  ### Creating applications
     8  
     9  Using `fn`:
    10  
    11  ```sh
    12  fn apps create --config k1=v1 --config k2=v2 myapp
    13  ```
    14  
    15  Or using a cURL:
    16  
    17  ```sh
    18  curl -H "Content-Type: application/json" -X POST -d '{
    19      "app": {
    20          "name":"myapp-curl",
    21          "config": {
    22              "k1": "v1",
    23              "k2": "v2"
    24          }
    25      }
    26  }' http://localhost:8080/v1/apps
    27  ```
    28  
    29  ### App Example
    30  
    31  ```json
    32  {
    33      "name": "myapp",
    34      "myconfig": "config"
    35  }
    36  ```
    37  
    38  ### Properties
    39  
    40  #### name (string)
    41  
    42  `name` is a property that references an unique app.
    43  
    44  App names are immutable. When updating apps with `PATCH` requests, keep in mind that although you
    45  are able to update an app's configuration set, you cannot really rename it.
    46  
    47  #### config (object)
    48  
    49  `config` is a map of values passed to the route runtime in the form of
    50  environment variables.
    51  
    52  Note: Route level configuration overrides app level configuration.
    53  
    54  ## Routes
    55  
    56  ### Creating routes
    57  
    58  Using `fn`:
    59  
    60  ```sh
    61  fn routes create myapp /path --config k1=v1 --config k2=v2 --image iron/hello
    62  ```
    63  
    64  Or using a cURL:
    65  
    66  ```sh
    67  curl -H "Content-Type: application/json" -X POST -d '{
    68      "app": {
    69          "path": "/path",
    70          "image": "image",
    71          "config": {
    72              "k1": "v1",
    73              "k2": "v2"
    74          }
    75      }
    76  }' http://localhost:8080/v1/apps/myapp/routes
    77  ```
    78  
    79  ### Route Example
    80  ```json
    81  {
    82      "path": "/hello",
    83      "image": "iron/hello",
    84      "type": "sync",
    85      "memory": 128,
    86      "config": {
    87          "key": "value",
    88          "key2": "value2",
    89          "keyN": "valueN",
    90      },
    91      "headers": {
    92          "content-type": [
    93              "text/plain"
    94          ]
    95      }
    96  }
    97  ```
    98  
    99  ### Properties
   100  
   101  #### path (string)
   102  
   103  Represents a unique `route` in the API and is identified by the property `path` and `app`.
   104  
   105  Every `route` belongs to an `app`.
   106  
   107  Note: Route paths are immutable. If you need to change them, the appropriate approach
   108  is to add a new route with the modified path.
   109  
   110  #### image (string)
   111  
   112  `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).
   113  
   114  If no registry is provided and image is not available locally the API will try pull it from a default public registry.
   115  
   116  #### type (string)
   117  
   118  Options: `sync` and `async`
   119  
   120  `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.
   121  
   122  In `async` functions the request will be ended with a `call_id` and the function will be executed in the background.
   123  
   124  #### memory (number)
   125  
   126  `memory` defines the amount of memory (in megabytes) required to run this function.
   127  
   128  #### config (object of string values)
   129  
   130  `config` is a map of values passed to the route runtime in the form of
   131  environment variables.
   132  
   133  Note: Route level configuration overrides app level configuration.
   134  
   135  #### headers (object of array of string)
   136  
   137  `header` is a set of headers that will be sent in the function execution response. The header value is an array of strings.
   138  
   139  #### format (string)
   140  
   141  `format` defines if the function is running or not in `hot function` mode.
   142  
   143  To define the function execution as `hot function` you set it as one of the following formats:
   144  
   145  - `"http"`
   146  
   147  ### 'Hot function' Only Properties
   148  
   149  This properties are only used if the function is in `hot function` mode
   150  
   151  #### max_concurrency (string)
   152  
   153  This property defines the maximum amount of concurrent hot functions instances the function should have (per IronFunction node).