swagger.yaml

swagger: '2.0'
info:
  title: Innkeeper (Route Manager)
  description: |
    API for manipulating Fashion Store routes. It allows all teams to access
    and define non-wildcard paths to all relevant users in employee realm as
    well as, some service realm clients (e.g. CMS). Creation of wildcard routes
    is reserved for maintainers of this API as it requires special care.
  version: 3.0.0
host: innkeeper.host.eu
schemes:
  - https
basePath: /
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  company:
    type: oauth2
    authorizationUrl: 'https://auth.provider.com/z/XUI/#login/'
    flow: implicit
    scopes:
      routes.read: |
        Reading (listing) all the routes
      routes.write: |
        All operations on routes with strict path matching.
      routes.admin: |
        All operations on all routes, including ones with regex path matching.
paths:
  '/hosts':
    get:
      security:
        - company:
          - routes.read
      summary: Returns the list of available hosts.
      responses:
        '200':
          description: An array of available hosts.
          schema:
            type: array
            items:
              $ref: '#/definitions/Host'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/paths':
    post:
      security:
        - company:
          - routes.write
      summary: Creates a new path resource that belongs to the team of the creator.
      parameters:
        - name: path
          in: body
          description: Path to create.
          required: true
          schema:
            $ref: '#/definitions/PathIn'
      responses:
        '201':
          description: The path is created.
          schema:
            $ref: '#/definitions/PathOut'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    get:
      security:
        - company:
          - routes.read
      summary: A list of available paths.
      parameters:
        - name: owned_by_team
          in: query
          type: string
          required: false
        - name: uri
          in: query
          type: string
          required: false
      responses:
        '200':
          description: Array of paths.
          schema:
            type: array
            items:
              $ref: '#/definitions/PathOut'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/paths/{id}':
    get:
      security:
        - company:
          - routes.read
      summary: Information about a single path.
      parameters:
        - name: id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: A path with a given `id`.
          schema:
            $ref: '#/definitions/PathOut'
        '404':
          description: Happens when path does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      security:
        - company:
          - routes.write
      summary: Partially update a path.
      parameters:
        - name: id
          in: path
          type: string
          required: true
        - name: pathPatch
          in: body
          description: Path values to update.
          required: true
          schema:
            $ref: '#/definitions/PathPatch'
      responses:
        '200':
          description: The updated path.
          schema:
            $ref: '#/definitions/PathOut'
        '404':
          description: Happens when path does not exist.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - company:
          - routes.write
      summary: Deletes a path
      parameters:
        - name: id
          in: path
          type: string
          required: true
      description: |
        Deleting a path is only allowed for a client that is part of the team
        owning it or has admin credentials.
      responses:
        '200':
          description: Empty response
        '403':
          description: |
            Happens in a case of insufficient permissions.
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Happens when trying to delete a non-existent Path.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/routes':
    get:
      security:
        - company:
          - routes.read
      summary: Returns the list of all the routes.
      parameters:
        - name: name
          in: query
          description: The name of the route to filter for
          required: false
          type: string
        - name: owned_by_team
          in: query
          description: The team name to filter for
          required: false
          type: string
        - name: uri
          in: query
          description: The path uri to filter for
          required: false
          type: string
        - name: description
          in: query
          description: The route description to filter for
          required: false
          type: string
        - name: path_id
          in: query
          description: The path id to filter for
          required: false
          type: integer
          format: int64
        - name: id
          in: query
          description: The route id to filter for
          required: false
          type: integer
          format: int64
        - name: embed
          in: query
          description: The subresources to embed (path, hosts)
          required: false
          type: string
        - name: limit
          in: query
          description: the limit for a paginated query
          required: false
          type: integer
          format: int64
        - name: offset
          in: query
          description: the offset for a paginated query, if missing an limit is present it defaults to 0
          required: false
          type: integer
          format: int64
      responses:
        '200':
          description: An array of routes
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteOut'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    post:
      security:
        - company:
          - routes.write
      summary: Creating a route with specified name.
      parameters:
        - name: route
          in: body
          description: Route to add.
          required: true
          schema:
            $ref: '#/definitions/RouteIn'
      responses:
        '201':
          description: The route is created.
          schema:
            $ref: '#/definitions/RouteOut'
        '403':
          description: |
            Usually happens in a case of insufficient permissions.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - company:
          - routes.write
      summary: Deletes paths based on the provided filters.
      description: |
        If the provided token is not an admin token, only routes belonging
        to the team associated with the provided token are deleted.
      parameters:
        - name: name
          in: query
          description: The name of the route to filter for
          required: false
          type: string
        - name: owned_by_team
          in: query
          description: The team name to filter for
          required: false
          type: string
        - name: uri
          in: query
          description: The path uri to filter for
          required: false
          type: string
        - name: description
          in: query
          description: The route description to filter for
          required: false
          type: string
        - name: path_id
          in: query
          description: The path id to filter for
          required: false
          type: integer
          format: int64
        - name: id
          in: query
          description: The route id to filter for
          required: false
          type: integer
          format: int64
      responses:
        '200':
          description: The amount of routes that were deleted.
        '403':
          description: Happens in a case of insufficient permissions.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/current-routes':
    get:
      security:
        - company:
          - routes.read
      summary: Returns the list of all the active routes.
      parameters:
        - name: snapshot-timestamp
          in: query
          description: |
            the timestamp to use for computing the snapshot
            it is mandatory if offset is present and greater than zero
          required: false
          type: string
          format: date-time
        - name: limit
          in: query
          description: the limit for a paginated query
          required: false
          type: integer
          format: int64
        - name: offset
          in: query
          description: |
            the offset for a paginated query, if missing an limit is present it defaults to 0
          required: false
          type: integer
          format: int64
      responses:
        '200':
          description: An array of routes
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteOut'
          headers:
            X-Snapshot-Timestamp:
              type: string
              format: date-time
              description: |
                The timestamp used for computing the snapshot.
            X-Last-Update:
              type: string
              format: date-time
              description: |
                The timestamp for the last update to the routes (create, update, delete).
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/routes/{id}':
    get:
      security:
        - company:
          - routes.read
      summary: Information about a single route.
      parameters:
        - name: id
          in: path
          type: string
          required: true
        - name: embed
          in: query
          description: The subresources to embed (path, hosts)
          required: false
          type: string
      responses:
        '200':
          description: A route with a given `id`.
          schema:
            $ref: '#/definitions/RouteOut'
        '404':
          description: Happens when trying to access a non-existent Route.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      security:
        - company:
          - routes.write
      summary: Partially update a route.
      parameters:
        - name: id
          in: path
          type: string
          required: true
        - name: routePatch
          in: body
          description: Route values to update.
          required: true
          schema:
            $ref: '#/definitions/RoutePatch'
      responses:
        '200':
          description: The updated route.
          schema:
            $ref: '#/definitions/RouteOut'
        '403':
          description: |
            Usually happens in a case of insufficient permissions.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
    delete:
      security:
        - company:
          - routes.write
      summary: Deletes a route
      parameters:
        - name: id
          in: path
          type: string
          required: true
      description: |
        Deleting a path is only allowed for a client that is part of the team
        owning it or has admin credentials.
      responses:
        '200':
          description: Empty response
        '403':
          description: |
            Happens in a case of insufficient permissions.
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Happens when trying to delete a non-existent Route.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
  '/updated-routes/{timestamp}':
    get:
      security:
        - company:
          - routes.read
      parameters:
        - name: timestamp
          in: path
          type: string
          required: true
          format: ISO-8601
      summary: Returns a list of route updates after the provided timestamp.
      responses:
        '200':
          description: An array of route updates
          schema:
            type: array
            items:
              $ref: '#/definitions/RouteChange'
        default:
          description: A processing or an unexpected error.
          schema:
            $ref: '#/definitions/Error'
definitions:
  RouteIn:
    required:
      - path_id
      - name
      - uses_common_filters
      - predicates
      - filters
      - endpoint
    properties:
      path_id:
        type: integer
        format: int64
      name:
        type: string
        pattern: /[A-Z][A-Z0-9_]*
        description: The name of the route in the ROUTE_NAME format
      uses_common_filters:
        type: boolean
        description: Specifies if the route uses the configured common filters
      description:
        type: string
        description: Human readable description for the route
      activate_at:
        type: string
        description: The ISO-8601 date time when the route will be activated
      disable_at:
        type: string
        description: The ISO-8601 date time when the route will be deactivated
      predicates:
        type: array
        items:
          $ref: '#/definitions/Predicate'
        description: |
          Definition of predicates to be applied
      filters:
        type: array
        items:
          $ref: '#/definitions/Filter'
        description: |
          Definition of filters to be applied. fashionStore() filter is a mandatory filter and
          must always present
      endpoint:
        type: string
        description: |
          A valid http(s) endpoint that the request should be routed to
      host_ids:
        type: array
        items:
          type: integer
          format: int64
        description: |
          Ids of the hosts to which route has to be applied. This list must be
          a sublist of the host ids for the path.
  RoutePatch:
    properties:
      uses_common_filters:
        type: boolean
        description: Specifies if the route uses the configured common filters
      description:
        type: string
        description: Human readable description for the route
      route:
        $ref: '#/definitions/RouteData'
      host_ids:
        type: array
        items:
          type: integer
          format: int64
        description: |
          Ids of the hosts to which route has to be applied. This list must be
          a sublist of the host ids for the path.
  RouteData:
    properties:
      predicates:
        type: array
        items:
          $ref: '#/definitions/Predicate'
        description: |
          Definition of predicates to be applied
      filters:
        type: array
        items:
          $ref: '#/definitions/Filter'
        description: |
          Definition of filters to be applied.
      endpoint:
        type: string
        description: |
          A valid http(s) endpoint that the request should be routed to
  RouteOut:
    required:
      - id
      - path_id
      - name
      - uses_common_filters
      - predicates
      - filters
      - endpoint
      - created_at
      - activate_at
      - created_by
    properties:
      id:
        type: integer
        format: int64
      path_id:
        type: integer
        format: int64
      name:
        type: string
        pattern: \[a-zA-Z][a-zA-Z0-9_]*
        description: The name of the route in the ROUTE_NAME format
      uses_common_filters:
        type: boolean
        description: Specifies if the route uses the configured common filters
      description:
        type: string
        description: Human readable description for the route
      created_at:
        type: string
        description: The ISO-8601 date time when the route has been created
      activate_at:
        type: string
        description: The ISO-8601 date time when the route will be activated
      disable_at:
        type: string
        description: The ISO-8601 date time when the route will be deactivated
      created_by:
        type: string
      predicates:
        type: array
        items:
          $ref: '#/definitions/Predicate'
        description: |
          Definition of predicates to be applied
      filters:
        type: array
        items:
          $ref: '#/definitions/Filter'
        description: |
          Definition of filters to be applied.
      endpoint:
        type: string
        description: |
          A valid http(s) endpoint that the request should be routed to
      host_ids:
        type: array
        items:
          type: integer
          format: int64
        description: |
          Ids of the hosts to which route has to be applied. This list is a sublist
          of the host ids for the path.
      hosts:
        type: array
        items:
          $ref: '#/definitions/Host'
        description: |
          A list of Hosts resolved by host_ids.
      path:
        $ref: '#/definitions/PathOut'
  RouteChange:
    required:
      - type
      - timestamp
      - name
      - eskip
    properties:
      type:
        type: string
        description: the type of the RouteChange (create update or delete)
      timestamp:
        type: string
        description: The ISO-8601 date time when the route will be activated
      name:
        type: string
        description: Route name
      eskip:
        type: string
        description: The Route in eskip format
  Predicate:
    required:
      - name
      - args
    properties:
      name:
        type: string
        description: |
          The name of the predicate, as it is definined in Skipper
      args:
        description: The arguments for the predicate, can be string or float64
        type: array
        items:
          $ref: '#/definitions/Arg'
  Filter:
    required:
      - name
      - args
    properties:
      name:
        type: string
        description: |
          The name of the filter, as it is definined in Skipper
      args:
        description: The arguments for the filter, can be string or float64
        type: array
        items:
          $ref: '#/definitions/Arg'
  Arg:
    required:
      - type
      - value
    properties:
      type:
        type: string
        description: Must be one of [number, string, regex]
      value:
        description: A value representing the type
  Host:
    required:
      - id
      - name
    properties:
      id:
        type: string
        format: int32
      name:
        type: string
    example: |
      {
        "id": "1",
        "name": "zalando.de"
      }
  PathIn:
    required:
      - uri
      - host_ids
    properties:
      uri:
        type: string
        description: empty uri are not allowed
        pattern: .+
      host_ids:
        type: array
        items:
          type: integer
          format: int64
      has_star:
        type: boolean
        description: the path will be serialized as a PathSubtree predicate
      is_regex:
        type: boolean
        description: the path will be serialized as a PathRegexp predicate
      owned_by_team:
        type: string
        description: defines the team owning this path.
    example: |
      {
        "uri": "/cart",
        "host_ids": [1, 2]
      }
  PathOut:
    required:
      - id
      - owned_by_team
      - created_by
      - uri
      - host_ids
      - created_at
    properties:
      id:
        type: string
      owned_by_team:
        type: string
      created_by:
        type: string
      uri:
        type: string
      host_ids:
        type: array
        items:
          type: integer
          format: int64
      created_at:
        type: string
        format: date-time
      has_star:
        type: boolean
      is_regex:
        type: boolean
    example: |
      {
        "id": "1",
        "owned_by_team": "coast",
        "created_by": "user",
        "uri": "/cart",
        "has_star": false,
        "is_regex": false,
        "host_ids": [1, 2],
        "created_at": "1985-04-12T23:20:50.52Z"
      }
  PathPatch:
    properties:
      owned_by_team:
        type: string
      host_ids:
        type: array
        items:
          type: integer
          format: int64
    example: |
      {
        "owned_by_team": "coast",
        "host_ids": [1, 2]
      }
  Error:
    required:
      - type
      - status
      - title
    properties:
      type:
        type: string
      status:
        type: integer
        format: int32
      title:
        type: string
        description: Short description of an error
      detail:
        type: string
        description: Detailed description of an error