swagger.yml

swagger: '2.0'
info:
  title: fn
  description: The open source serverless platform.
  version: "0.2.4"
# the domain of the service
host: "127.0.0.1:8080"
# array of all schemes that your API supports
schemes:
  - https
  - http
# will be prefixed to all paths
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
paths:
  /apps:
    get:
      summary: "Get all app names."
      description: "Get a list of all the apps in the system, returned in alphabetical order."
      tags:
        - Apps
      parameters:
        - name: cursor
          description: Cursor from previous response.next_cursor to begin results after, if any.
          required: false
          type: string
          in: query
        - name: per_page
          description: Number of results to return, defaults to 30. Max of 100.
          required: false
          type: integer
          in: query
      responses:
        200:
          description: List of apps.
          schema:
            $ref: '#/definitions/AppsWrapper'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: "Post new app"
      description: "Insert a new app"
      tags:
        - Apps
      parameters:
        - name: body
          in: body
          description: App to post.
          required: true
          schema:
            $ref: '#/definitions/AppWrapper'
      responses:
        200:
          description: App details and stats.
          schema:
            $ref: '#/definitions/AppWrapper'
        400:
          description: Parameters are missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: App already exists.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


  /apps/{app}:
    delete:
      summary: "Delete an app."
      description: "Delete an app."
      tags:
        - Apps
      parameters:
        - name: app
          in: path
          description: Name of the app.
          required: true
          type: string
      responses:
        200:
          description: Apps successfully deleted.
        404:
          description: App does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: "Get information for a app."
      description: "This gives more details about a app, such as statistics."
      tags:
        - Apps
      parameters:
        - name: app
          in: path
          description: name of the app.
          required: true
          type: string
      responses:
        200:
          description: App details and stats.
          schema:
            $ref: '#/definitions/AppWrapper'
        404:
          description: App does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: "Updates an app."
      description: "You can set app level settings here. "
      tags:
        - Apps
      parameters:
        - name: app
          in: path
          description: name of the app.
          required: true
          type: string
        - name: body
          in: body
          description: App to post.
          required: true
          schema:
            $ref: '#/definitions/AppWrapper'
      responses:
        200:
          description: App details and stats.
          schema:
            $ref: '#/definitions/AppWrapper'
        400:
          description: Parameters are missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: App does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/routes:
    post:
      summary: Create new Route
      description: Create a new route in an app, if app doesn't exists, it creates the app. Post does not skip validation of zero values.
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: name of the app.
          required: true
          type: string
        - name: body
          in: body
          description: One route to post.
          required: true
          schema:
            $ref: '#/definitions/RouteWrapper'
      responses:
        200:
          description: Route created
          schema:
            $ref: '#/definitions/RouteWrapper'
        400:
          description: Invalid route due to parameters being missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        409:
          description: Route already exists.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    get:
      summary: Get route list by app name.
      description: This will list routes for a particular app, returned in alphabetical order.
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: Name of app for this set of routes.
          required: true
          type: string
        - name: image
          description: Route image to match, exact.
          required: false
          type: string
          in: query
        - name: cursor
          description: Cursor from previous response.next_cursor to begin results after, if any.
          required: false
          type: string
          in: query
        - name: per_page
          description: Number of results to return, defaults to 30. Max of 100.
          required: false
          type: integer
          in: query
      responses:
        200:
          description: Route information
          schema:
            $ref: '#/definitions/RoutesWrapper'
        404:
          description: App does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/routes/{route}:
    put:
      summary: Create a Route if it does not exist. Update if it does. Will also create app if it does not exist. Put does not skip validation of zero values
      description: Update or Create a route
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: name of the app.
          required: true
          type: string
        - name: route
          in: path
          description: route path.
          required: true
          type: string
        - name: body
          in: body
          description: One route to post.
          required: true
          schema:
            $ref: '#/definitions/RouteWrapper'
      responses:
        200:
          description: Route created or updated
          schema:
            $ref: '#/definitions/RouteWrapper'
        400:
          description: Invalid route due to parameters being missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update a Route, Fails if the route or app does not exist. Accepts partial updates / skips validation of zero values.
      description: Update a route
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: name of the app.
          required: true
          type: string
        - name: route
          in: path
          description: route path.
          required: true
          type: string
        - name: body
          in: body
          description: One route to post.
          required: true
          schema:
            $ref: '#/definitions/RouteWrapper'
      responses:
        200:
          description: Route updated
          schema:
            $ref: '#/definitions/RouteWrapper'
        400:
          description: Invalid route due to parameters being missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        404:
          description: App / Route does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    get:
      summary: Gets route by name
      description: Gets a route by name.
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: Name of app for this set of routes.
          required: true
          type: string
        - name: route
          in: path
          description: Route name
          required: true
          type: string
      responses:
        200:
          description: Route information
          schema:
            $ref: '#/definitions/RouteWrapper'
        404:
          description: Route does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    delete:
      summary: Deletes the route
      tags:
        - Routes
      description: Deletes the route.
      parameters:
        - name: app
          in: path
          description: Name of app for this set of routes.
          required: true
          type: string
        - name: route
          in: path
          description: Route name
          required: true
          type: string
      responses:
        200:
          description: Route successfully deleted.
        404:
          description: Route does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/calls/{call}/log:
    get:
      summary: Get call logs
      description: Get call logs
      tags:
        - Call
        - Log
      parameters:
        - name: app
          description: App Name
          required: true
          type: string
          in: path
        - name: call
          description: Call ID.
          required: true
          type: string
          in: path
      responses:
        200:
          description: Log found
          schema:
            $ref:  '#/definitions/LogWrapper'
        404:
          description: Log not found.
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/calls/{call}:
    get:
      summary: Get call information
      description: Get call information
      tags:
        - Call
      parameters:
        - name: app
          description: app name
          required: true
          type: string
          in: path
        - name: call
          description: Call ID.
          required: true
          type: string
          in: path
      responses:
        200:
          description: Call found
          schema:
            $ref:  '#/definitions/CallWrapper'
        404:
          description: Call not found.
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/calls:
    get:
      summary: Get app-bound calls.
      description: Get app-bound calls can filter to route-bound calls, results returned in created_at, descending order (newest first).
      tags:
        - Call
      parameters:
        - name: app
          description: App name.
          required: true
          type: string
          in: path
        - name: path
          description: Route path to match, exact.
          required: false
          type: string
          in: query
        - name: cursor
          description: Cursor from previous response.next_cursor to begin results after, if any.
          required: false
          type: string
          in: query
        - name: per_page
          description: Number of results to return, defaults to 30. Max of 100.
          required: false
          type: integer
          in: query
        - name: from_time
          description: Unix timestamp in seconds, of call.created_at to begin the results at, default 0.
          required: false
          type: integer
          in: query
        - name: to_time
          description: Unix timestamp in seconds, of call.created_at to end the results at, defaults to latest.
          required: false
          type: integer
          in: query
      responses:
        200:
          description: Calls found
          schema:
            $ref:  '#/definitions/CallsWrapper'
        404:
          description: Calls not found.
          schema:
            $ref: '#/definitions/Error'

definitions:
  Route:
    type: object
    properties:
      app_id:
        type: string
        description: App ID
      path:
        type: string
        description: URL path that will be matched to this route
        readOnly: true
      image:
        description: Name of Docker image to use in this route. You should include the image tag, which should be a version number, to be more accurate. Can be overridden on a per route basis with route.image.
        type: string
      headers:
        type: object
        description: Map of http headers that will be sent with the response
        additionalProperties:
          type: array
          items:
            type: string
      memory:
        type: integer
        format: uint64
        description: Max usable memory for this route (MiB).
      cpus:
        type: string
        description: Max usable CPU cores for this route. Value in MilliCPUs (eg. 500m) or as floating-point (eg. 0.5)
      type:
        enum:
          - sync
          - async
        description: Route type
        type: string
      format:
        enum:
          - default
          - http
          - json
        description: Payload format sent into function.
        type: string
      config:
        type: object
        description: Route configuration - overrides application configuration
        additionalProperties:
          type: string
      timeout:
        type: integer
        default: 30
        format: int32
        description: Timeout for executions of this route. Value in Seconds
      idle_timeout:
        type: integer
        default: 30
        format: int32
        description: Hot functions idle timeout before termination. Value in Seconds
      annotations:
        type: object
        description: Route annotations - this is a map of annotations attached to this route, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes
        additionalProperties:
          type: object
      created_at:
        type: string
        format: date-time
        description: Time when route was created. Always in UTC.
        readOnly: true
      updated_at:
        type: string
        format: date-time
        description: Most recent time that route was updated. Always in UTC.
        readOnly: true

  App:
    type: object
    properties:
      id:
        type: string
        description: App ID
        readOnly: true
      name:
        type: string
        description: "Name of this app. Must be different than the image name. Can ony contain alphanumeric, -, and _."
        readOnly: true
      config:
        type: object
        description: Application function configuration, applied to all routes.
        additionalProperties:
          type: string
      annotations:
        type: object
        description: Application annotations - this is a map of annotations attached to this app, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes
        additionalProperties:
          type: object
      created_at:
        type: string
        format: date-time
        description: Time when app was created. Always in UTC.
        readOnly: true
      updated_at:
        type: string
        format: date-time
        description: Most recent time that app was updated. Always in UTC.
        readOnly: true

  RoutesWrapper:
    type: object
    required:
      - routes
    properties:
      next_cursor:
        type: string
        description: cursor to send with subsequent request to receive the next page, if non-empty
        readOnly: true
      routes:
        type: array
        items:
          $ref: '#/definitions/Route'
      error:
        $ref: '#/definitions/ErrorBody'

  RouteWrapper:
    type: object
    required:
      - route
    properties:
      message:
        type: string
      error:
        $ref: '#/definitions/ErrorBody'
      route:
        $ref: '#/definitions/Route'

  AppsWrapper:
    type: object
    required:
      - apps
    properties:
      next_cursor:
        type: string
        description: cursor to send with subsequent request to receive the next page, if non-empty
        readOnly: true
      apps:
        type: array
        items:
          $ref: '#/definitions/App'
      error:
        $ref: '#/definitions/ErrorBody'

  AppWrapper:
    type: object
    required:
      - app
    properties:
      app:
        $ref: '#/definitions/App'
      error:
        $ref: '#/definitions/ErrorBody'

  CallsWrapper:
    type: object
    required:
      - calls
    properties:
      next_cursor:
        type: string
        description: cursor to send with subsequent request to receive the next page, if non-empty
        readOnly: true
      calls:
        type: array
        items:
          $ref: '#/definitions/Call'
      error:
        $ref: '#/definitions/ErrorBody'

  CallWrapper:
    type: object
    required:
      - call
    properties:
      call:
        $ref: '#/definitions/Call'
        description: "Call object."

  LogWrapper:
    type: object
    required:
      - log
    properties:
      log:
        $ref: '#/definitions/Log'
        description: "Call log entry."

  Log:
    type: object
    properties:
      call_id:
        type: string
        description: Call UUID ID
      log:
        type: string # maybe bytes, long logs wouldn't fit into string type

  Call:
    type: object
    properties:
      id:
        type: string
        description: Call UUID ID.
        readOnly: true
      status:
        type: string
        description: Call execution status.
        readOnly: true
      error:
        type: string
        description: Call execution error, if status is 'error'.
        readOnly: true
      app_id:
        type: string
        description: App ID that is assigned to a route that is being executed.
        readOnly: true
      path:
        type: string
        description: App route that is being executed.
        readOnly: true
      created_at:
        type: string
        format: date-time
        description: Time when call was submitted. Always in UTC.
        readOnly: true
      started_at:
        type: string
        format: date-time
        description: Time when call started execution. Always in UTC.
        readOnly: true
      completed_at:
        type: string
        format: date-time
        description: Time when call completed, whether it was successul or failed. Always in UTC.
        readOnly: true
      stats:
        type: array
        items:
          $ref: '#/definitions/Stat'
        description: A histogram of stats for a call, each is a snapshot of a calls state at the timestamp.
        readOnly: true

  Stat:
    type: object
    properties:
      timestamp:
        type: string
        format: date-time
      metrics:
        type: object
        properties:
          net_rx:
            type: integer
            format: int64
          net_tx:
            type: integer
            format: int64
          mem_limit:
            type: integer
            format: int64
          mem_usage:
            type: integer
            format: int64
          disk_read:
            type: integer
            format: int64
          disk_write:
            type: integer
            format: int64
          cpu_user:
            type: integer
            format: int64
          cpu_total:
            type: integer
            format: int64
          cpu_kernel:
            type: integer
            format: int64

  ErrorBody:
    type: object
    properties:
      message:
        type: string
        readOnly: true
      fields:
        type: string
        readOnly: true

  Error:
    type: object
    properties:
      error:
        $ref: '#/definitions/ErrorBody'