fn-serverless/docs/swagger.yml

# This is the IronFunctions API spec
# If you make changes here, remember to run `go generate` in api/models/ and
# api/server to make sure you use the changes.

swagger: '2.0'
info:
  title: IronFunctions
  description: The open source serverless platform.
  version: "0.1.18"
# 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."
      tags:
        - Apps
      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'
        500:
          description: Could not accept app due to internal error.
          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.
    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'
    put:
      summary: "Create/update a 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'
        500:
          description: Could not accept app due to internal error.
          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
      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:
        201:
          description: Route created
          schema:
            $ref: '#/definitions/RouteWrapper'
        400:
          description: One or more of the routes were invalid due to parameters being missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Could not accept routes due to internal error.
          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.
      tags:
        - Routes
      parameters:
        - name: app
          in: path
          description: Name of app for this set of routes.
          required: true
          type: string
      responses:
        200:
          description: Route information
          schema:
            $ref: '#/definitions/RoutesWrapper'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /apps/{app}/routes/{route}:
    put:
      summary: Update a Route
      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:
        201:
          description: Route updated
          schema:
            $ref: '#/definitions/RouteWrapper'
        400:
          description: One or more of the routes were invalid due to parameters being missing or invalid.
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Could not accept routes due to internal error.
          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.

  /tasks:
    get:
      summary: Get next task.
      description: Gets the next task in the queue, ready for processing. Titan may return <=n tasks. Consumers should start processing tasks in order. Each returned task is set to `status` "running" and `started_at` is set to the current time. No other consumer can retrieve this task.
      tags:
        - Tasks
      parameters:
        - name: "n"
          in: query
          default: 1
          description: Number of tasks to return.
          type: integer
          format: int32
      responses:
        200:
          description: Task information
          schema:
            $ref:  '#/definitions/TaskWrapper'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'


definitions:
  Route:
    allOf:
      - type: object
        properties:
          app_name:
            type: string
            description: "App this route belongs to."
            readOnly: true
          path:
            type: string
            description: URL path that will be matched to this route
          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: string
            description: Map of http headers that will be sent with the response
          memory:
            type: integer
            format: int64
            description: Max usable memory for this route (MiB).
          type:
            enum:
              - sync
              - async
            description: Route type
          format:
            enum:
              - default
              - http
              - json
            description: Payload format sent into function.
          max_concurrency:
            type: integer
            format: int32
            description: Maximum number of hot containers concurrency
          config:
            type: object
            description: Route configuration - overrides application configuration
            additionalProperties:
              type: string

  App:
    type: object
    properties:
      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 configuration
        additionalProperties:
          type: string

  RoutesWrapper:
    type: object
    required:
      - routes
    properties:
      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:
      apps:
        type: array
        items:
          $ref: '#/definitions/App'

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

  Task:
    allOf:
      - $ref: "#/definitions/NewTask"
      - type: object
        properties:
          group_name:
            type: string
            description: "Group this task belongs to."
            readOnly: true
          error:
            type: string
            description: "The error message, if status is 'error'. This is errors due to things outside the task itself. Errors from user code will be found in the log."
          reason:
            type: string
            description: |
              Machine usable reason for task being in this state.
              Valid values for error status are `timeout | killed | bad_exit`.
              Valid values for cancelled status are `client_request`.
              For everything else, this is undefined.
            enum:
              - timeout
              - killed
              - bad_exit
              - client_request
          created_at:
            type: string
            format: date-time
            description: Time when task was submitted. Always in UTC.
            readOnly: true
          started_at:
            type: string
            format: date-time
            description: Time when task started execution. Always in UTC.
          completed_at:
            type: string
            format: date-time
            description: Time when task completed, whether it was successul or failed. Always in UTC.
          # We maintain a doubly linked list of the retried task to the
          # original task.
          retry_of:
            type: string
            description: If this field is set, then this task is a retry of the ID in this field.
            readOnly: true
          retry_at:
            type: string
            description: If this field is set, then this task was retried by the task referenced in this field.
            readOnly: true
          env_vars:
            # this is a map: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#model-with-mapdictionary-properties
            type: object
            description: Env vars for the task. Comes from the ones set on the Group.
            additionalProperties:
              type: string

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

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

  NewTask:
    type: object
    required:
      - image
    properties:
      image:
        type: string
        description: Name of Docker image to use. This is optional and can be used to override the image defined at the group level.
      payload:
        type: string
        # 256k
        # maxLength breaks ruby generator too: https://github.com/iron-io/worker_ruby/blob/0aa9236ce5060af3f15758937712973f80dd54fe/lib/iron_titan/models/task.rb#L272
        # maxLength: 268435456
        description: Payload for the task. This is what you pass into each task to make it do something.

  TaskWrapper:
    type: object
    required:
      - task
    properties:
      task:
        $ref: '#/definitions/Task'