swagger.yaml

# This is the Open API 2.0 (Swagger) interface for Open Service Broker API.
# Every attempt will be made to make the Open API 2.0 version of OSB API
# accurately represent the written specification. If the spec and this document
# conflict, the spec is the authority.

swagger: '2.0'

info:
  title: Open Service Broker API
  description: >-
    The Open Service Broker API defines an HTTP(S) interface between Platforms
    and Service Brokers.
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  contact:
    name: Open Service Broker API
    url: 'https://www.openservicebrokerapi.org/'
    email: open-service-broker-api@googlegroups.com
  version: master - might contain changes that are not yet released

host: localhost:3000
schemes:
  - http
  - https

consumes:
  - application/json
produces:
  - application/json

paths:
  /v2/catalog:
    parameters:
      - $ref: '#/parameters/APIVersion'
      - $ref: '#/parameters/OriginatingIdentity'
      - $ref: '#/parameters/RequestIdentity'
    get:
      summary: get the catalog of services that the service broker offers
      tags:
        - Catalog
      operationId: catalog.get
      responses:
        '200':
          description: catalog response
          schema:
            $ref: '#/definitions/Catalog'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        default:
          $ref: '#/responses/ErrorUnexpected'
  '/v2/service_instances/{instance_id}':
    parameters:
      - $ref: '#/parameters/APIVersion'
      - $ref: '#/parameters/OriginatingIdentity'
      - $ref: '#/parameters/RequestIdentity'
      - name: instance_id
        in: path
        description: instance id of instance to provision
        required: true
        type: string
    put:
      summary: provision a service instance
      tags:
        - ServiceInstances
      operationId: serviceInstance.provision
      parameters:
        - name: body
          in: body
          description: parameters for the requested service instance provision
          required: true
          schema:
            $ref: '#/definitions/ServiceInstanceProvisionRequest'
        - $ref: '#/parameters/accepts_incomplete'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceInstanceProvisionResponse'
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ServiceInstanceProvisionResponse'
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/ServiceInstanceAsyncOperation'
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '409':
          $ref: '#/responses/ErrorConflict'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        '422':
          $ref: '#/responses/ErrorUnprocessableEntity'
        default:
          $ref: '#/responses/ErrorUnexpected'
    patch:
      summary: update a service instance
      tags:
        - ServiceInstances
      operationId: serviceInstance.update
      parameters:
        - name: body
          in: body
          description: parameters for the requested service instance update
          required: true
          schema:
            $ref: '#/definitions/ServiceInstanceUpdateRequest'
        - $ref: '#/parameters/accepts_incomplete'
      responses:
        '200':
          description: OK
          schema:
            type: object
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/ServiceInstanceAsyncOperation'
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        '422':
          $ref: '#/responses/ErrorUnprocessableEntity'
        default:
          $ref: '#/responses/ErrorUnexpected'
    delete:
      summary: deprovision a service instance
      tags:
        - ServiceInstances
      operationId: serviceInstance.deprovision
      parameters:
        - $ref: '#/parameters/accepts_incomplete'
        - $ref: '#/parameters/service_id'
        - $ref: '#/parameters/plan_id'
      responses:
        '200':
          description: OK
          schema:
            type: object
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/AsyncOperation'
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '410':
          $ref: '#/responses/ErrorGone'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        '422':
          $ref: '#/responses/ErrorUnprocessableEntity'
        default:
          $ref: '#/responses/ErrorUnexpected'
    get:
      summary: gets a service instance
      tags:
        - ServiceInstances
      operationId: serviceInstance.get
      parameters:
        - name: service_id
          in: query
          description: id of the service associated with the instance
          type: string
        - name: plan_id
          in: query
          description: id of the plan associated with the instance
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceInstanceResource'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '404':
          $ref: '#/responses/ErrorNotFound'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        default:
          $ref: '#/responses/ErrorUnexpected'
  '/v2/service_instances/{instance_id}/last_operation':
    parameters:
      - $ref: '#/parameters/APIVersion'
      - $ref: '#/parameters/OriginatingIdentity'
      - $ref: '#/parameters/RequestIdentity'
      - name: instance_id
        in: path
        description: instance id of instance to provision
        required: true
        type: string
    get:
      summary: last requested operation state for service instance
      tags:
        - ServiceInstances
      operationId: serviceInstance.lastOperation.get
      parameters:
        - name: service_id
          in: query
          description: id of the service associated with the instance
          type: string
        - name: plan_id
          in: query
          description: id of the plan associated with the instance
          type: string
        - name: operation
          in: query
          description: a provided identifier for the operation
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/LastOperationResource'
          headers:
            RetryAfter:
              description: Indicates when to retry the request
              type: string
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '404':
          $ref: '#/responses/ErrorNotFound'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '410':
          $ref: '#/responses/ErrorGone'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        default:
          $ref: '#/responses/ErrorUnexpected'
  '/v2/service_instances/{instance_id}/service_bindings/{binding_id}/last_operation':
    parameters:
      - $ref: '#/parameters/APIVersion'
      - $ref: '#/parameters/OriginatingIdentity'
      - $ref: '#/parameters/RequestIdentity'
      - name: instance_id
        in: path
        description: instance id of instance to provision
        required: true
        type: string
      - name: binding_id
        in: path
        description: binding id of binding to create
        required: true
        type: string
    get:
      summary: last requested operation state for service binding
      tags:
        - ServiceBindings
      operationId: serviceBinding.lastOperation.get
      parameters:
        - name: service_id
          in: query
          description: id of the service associated with the instance
          type: string
        - name: plan_id
          in: query
          description: id of the plan associated with the instance
          type: string
        - name: operation
          in: query
          description: a provided identifier for the operation
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/LastOperationResource'
          headers:
            RetryAfter:
              description: Indicates when to retry the request
              type: string
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '404':
          $ref: '#/responses/ErrorNotFound'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '410':
          $ref: '#/responses/ErrorGone'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        default:
          $ref: '#/responses/ErrorUnexpected'
  '/v2/service_instances/{instance_id}/service_bindings/{binding_id}':
    parameters:
      - $ref: '#/parameters/APIVersion'
      - $ref: '#/parameters/OriginatingIdentity'
      - $ref: '#/parameters/RequestIdentity'
      - name: instance_id
        in: path
        description: instance id of instance to provision
        required: true
        type: string
      - name: binding_id
        in: path
        description: binding id of binding to create
        required: true
        type: string
    put:
      summary: generation of a service binding
      tags:
        - ServiceBindings
      operationId: serviceBinding.binding
      parameters:
        - name: body
          in: body
          description: parameters for the requested service binding
          required: true
          schema:
            $ref: '#/definitions/ServiceBindingRequest'
        - $ref: '#/parameters/accepts_incomplete'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceBindingResponse'
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ServiceBindingResponse'
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/AsyncOperation'
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '409':
          $ref: '#/responses/ErrorConflict'
        '410':
          $ref: '#/responses/ErrorGone'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        '422':
          $ref: '#/responses/ErrorUnprocessableEntity'
        default:
          $ref: '#/responses/ErrorUnexpected'
    delete:
      summary: deprovision of a service binding
      tags:
        - ServiceBindings
      operationId: serviceBinding.unbinding
      parameters:
        - $ref: '#/parameters/service_id'
        - $ref: '#/parameters/plan_id'
        - $ref: '#/parameters/accepts_incomplete'
      responses:
        '200':
          description: OK
          schema:
            type: object
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/AsyncOperation'
        '400':
          $ref: '#/responses/ErrorBadRequest'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '410':
          $ref: '#/responses/ErrorGone'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        '422':
          $ref: '#/responses/ErrorUnprocessableEntity'
        default:
          $ref: '#/responses/ErrorUnexpected'
    get:
      summary: gets a service binding
      tags:
        - ServiceBindings
      operationId: serviceBinding.get
      parameters:
        - name: service_id
          in: query
          description: id of the service associated with the instance
          type: string
        - name: plan_id
          in: query
          description: id of the plan associated with the instance
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ServiceBindingResource'
        '401':
          $ref: '#/responses/ErrorUnauthorized'
        '404':
          $ref: '#/responses/ErrorNotFound'
        '412':
          $ref: '#/responses/ErrorPreconditionFailed'
        default:
          $ref: '#/responses/ErrorUnexpected'

parameters:
  APIVersion:
    name: X-Broker-API-Version
    in: header
    description: version number of the Service Broker API that the Platform will use
    required: true
    type: string
  OriginatingIdentity:
    name: X-Broker-API-Originating-Identity
    in: header
    description: identity of the user that initiated the request from the Platform
    type: string
  RequestIdentity:
    name: X-Broker-API-Request-Identity
    in: header
    description: idenity of the request from the Platform
    type: string
  accepts_incomplete:
    name: accepts_incomplete
    in: query
    description: asynchronous operations supported
    type: boolean
  service_id:
    name: service_id
    in: query
    description: id of the service associated with the instance being deleted
    required: true
    type: string
  plan_id:
    name: plan_id
    in: query
    description: id of the plan associated with the instance being deleted
    required: true
    type: string

responses:
  ErrorBadRequest:
    description: Bad Request
    schema:
      $ref: '#/definitions/Error'
  ErrorUnauthorized:
    description: Unauthorized
    schema:
      $ref: '#/definitions/Error'
  ErrorNotFound:
    description: Not Found
    schema:
      $ref: '#/definitions/Error'
  ErrorConflict:
    description: Conflict
    schema:
      $ref: '#/definitions/Error'
  ErrorGone:
    description: Gone
    schema:
      $ref: '#/definitions/Error'
  ErrorPreconditionFailed:
    description: Precondition Failed
    schema:
      $ref: '#/definitions/Error'
  ErrorUnprocessableEntity:
    description: Unprocessable Entity
    schema:
      $ref: '#/definitions/Error'
  ErrorUnexpected:
    description: Unexpected
    schema:
      $ref: '#/definitions/Error'

definitions:
  Catalog:
    type: object
    properties:
      services:
        type: array
        items:
          $ref: '#/definitions/Service'
  Service:
    type: object
    required:
      - name
      - id
      - description
      - bindable
      - plans
    properties:
      name:
        type: string
      id:
        type: string
      description:
        type: string
      tags:
        type: array
        items:
          type: string
      requires:
        type: array
        items:
          type: string
          enum:
            - syslog_drain
            - route_forwarding
            - volume_mount
      bindable:
        type: boolean
      instances_retrievable:
        type: boolean
      bindings_retrievable:
        type: boolean
      allow_context_updates:
        type: boolean
      metadata:
        $ref: '#/definitions/Metadata'
      dashboard_client:
        $ref: '#/definitions/DashboardClient'
      binding_rotatable:
        type: boolean
      plan_updateable:
        type: boolean
      plans:
        type: array
        items:
          $ref: '#/definitions/Plan'
  DashboardClient:
    type: object
    required:
      - id
      - secret
    properties:
      id:
        type: string
      secret:
        type: string
      redirect_uri:
        type: string
  Plan:
    type: object
    required:
      - id
      - name
      - description
    properties:
      id:
        type: string
      name:
        type: string
      description:
        type: string
      metadata:
        $ref: '#/definitions/Metadata'
      free:
        type: boolean
        default: true
      bindable:
        type: boolean
      plan_updateable:
        type: boolean
      schemas:
        $ref: '#/definitions/SchemasObject'
      maximum_polling_duration:
        type: integer
      maintenance_info:
        $ref: '#/definitions/MaintenanceInfo'
      binding_rotatable:
        type: boolean
        default: false
  SchemasObject:
    type: object
    properties:
      service_instance:
        $ref: '#/definitions/ServiceInstanceSchemaObject'
      service_binding:
        $ref: '#/definitions/ServiceBindingSchemaObject'
  ServiceInstanceSchemaObject:
    type: object
    properties:
      create:
        $ref: '#/definitions/SchemaParameters'
      update:
        $ref: '#/definitions/SchemaParameters'
  ServiceBindingSchemaObject:
    type: object
    properties:
      create:
        $ref: '#/definitions/SchemaParameters'
  SchemaParameters:
    type: object
    properties:
      parameters:
        $ref: '#/definitions/JSONSchemaObject'
  JSONSchemaObject:
    type: object
  ServiceInstanceResource:
    type: object
    properties:
      service_id:
        type: string
      plan_id:
        type: string
      dashboard_url:
        type: string
      parameters:
        type: object
      maintenance_info:
        $ref: '#/definitions/MaintenanceInfo'
      metadata:
        $ref: '#/definitions/ServiceInstanceMetadata'
  ServiceInstanceProvisionRequest:
    type: object
    required:
      - service_id
      - plan_id
      - organization_guid
      - space_guid
    properties:
      service_id:
        type: string
      plan_id:
        type: string
      context:
        $ref: '#/definitions/Context'
      organization_guid:
        type: string
        x-deprecated: true
      space_guid:
        type: string
        x-deprecated: true
      parameters:
        type: object
      maintenance_info:
        $ref: '#/definitions/MaintenanceInfo'
  ServiceInstanceProvisionResponse:
    type: object
    properties:
      dashboard_url:
        type: string
      metadata:
        $ref: '#/definitions/ServiceInstanceMetadata'
  ServiceInstanceAsyncOperation:
    type: object
    properties:
      dashboard_url:
        type: string
      operation:
        type: string
      metadata:
        $ref: '#/definitions/ServiceInstanceMetadata'
  ServiceInstanceUpdateRequest:
    type: object
    required:
      - service_id
    properties:
      context:
        $ref: '#/definitions/Context'
      service_id:
        type: string
      plan_id:
        type: string
      parameters:
        type: object
      previous_values:
        $ref: '#/definitions/ServiceInstancePreviousValues'
      maintenance_info:
        $ref: '#/definitions/MaintenanceInfo'
  ServiceInstancePreviousValues:
    type: object
    properties:
      service_id:
        type: string
        x-deprecated: true
      plan_id:
        type: string
      organization_id:
        type: string
        x-deprecated: true
      space_id:
        type: string
        x-deprecated: true
      maintenance_info:
        $ref: '#/definitions/MaintenanceInfo'
  AsyncOperation:
    type: object
    properties:
      operation:
        type: string
  LastOperationResource:
    type: object
    required:
      - state
    properties:
      state:
        type: string
        enum:
          - in progress
          - succeeded
          - failed
      description:
        type: string
      instance_usable:
        type: boolean
      update_repeatable:
        type: boolean
  ServiceBindingResource:
    type: object
    properties:
      metadata:
        $ref: '#/definitions/ServiceBindingMetadata'
      credentials:
        type: object
      syslog_drain_url:
        type: string
      route_service_url:
        type: string
      volume_mounts:
        type: array
        items:
          $ref: '#/definitions/ServiceBindingVolumeMount'
      endpoints:
        type: array
        items:
          $ref: '#/definitions/ServiceBindingEndpoint'
      parameters:
        type: object
  ServiceBindingRequest:
    type: object
    required:
      - service_id
      - plan_id
    properties:
      context:
        $ref: '#/definitions/Context'
      service_id:
        type: string
      plan_id:
        type: string
      app_guid:
        type: string
        x-deprecated: true
      bind_resource:
        $ref: '#/definitions/ServiceBindingResourceObject'
      parameters:
        type: object
      predecessor_binding_id:
        type: string
  ServiceBindingResourceObject:
    type: object
    properties:
      app_guid:
        type: string
      route:
        type: string
  ServiceBindingResponse:
    type: object
    properties:
      metadata:
        $ref: '#/definitions/ServiceBindingMetadata'
      credentials:
        type: object
      syslog_drain_url:
        type: string
      route_service_url:
        type: string
      volume_mounts:
        type: array
        items:
          $ref: '#/definitions/ServiceBindingVolumeMount'
      endpoints:
        type: array
        items:
          $ref: '#/definitions/ServiceBindingEndpoint'
  ServiceBindingMetadata:
    type: object
    properties:
      expires_at:
        type: string
      renew_before:
        type: string
  ServiceBindingEndpoint:
    type: object
    required:
      - host
      - ports
    properties:
      host:
        type: string
      ports:
        type: array
        items:
          type: string
      protocol:
        type: string
        enum:
          - tcp
          - udp
          - all
        default: tcp
  ServiceBindingVolumeMount:
    type: object
    required:
      - driver
      - container_dir
      - mode
      - device_type
      - device
    properties:
      driver:
        type: string
      container_dir:
        type: string
      mode:
        type: string
        enum:
          - r
          - rw
      device_type:
        type: string
        enum:
          - shared
      device:
        $ref: '#/definitions/ServiceBindingVolumeMountDevice'
  ServiceBindingVolumeMountDevice:
    type: object
    required:
      - volume_id
    properties:
      volume_id:
        type: string
      mount_config:
        type: object
  ServiceInstanceMetadata:
    type: object
    properties:
      labels:
        type: object
      attributes:
        type: object
  MaintenanceInfo:
    type: object
    properties:
      version:
        type: string
      description:
        type: string
  Context:
    description: >-
      See [Context
      Conventions](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#context-object)
      for more details.
    type: object
  Metadata:
    description: >-
      See [Service Metadata
      Conventions](https://github.com/openservicebrokerapi/servicebroker/blob/master/profile.md#service-metadata)
      for more details.
    type: object
  Object:
    type: object
  Error:
    type: object
    properties:
      error:
        type: string
      description:
        type: string
      instance_usable:
        type: boolean
      update_repeatable:
        type: boolean
securityDefinitions:
  basicAuth:
    type: basic
security:
  - basicAuth: []

externalDocs:
  description: The official Open Service Broker API specification
  url: 'https://github.com/openservicebrokerapi/servicebroker/'