Use raml-util rather than pin to github content

#%RAML 0.8
title: Configurations
version: v1
baseUri: http://github.com/org/folio/lsp-apis
protocols: [ HTTPS ]

documentation:
  - title: Configuration API updating system wide configurations
    content: This documents the API calls that can be made to update configurations in the system

schemas:
  - configs: !include ../_schemas/kv_configurations.schema
  - config: !include ../_schemas/kv_configuration.schema
  - libraries: !include ../_schemas/library.schema

traits:
  - orderable: !include ../../raml-util/traits/orderable.raml
  - pageable:  !include ../../raml-util/traits/pageable.raml
  - searchable: !include ../../raml-util/traits/searchable.raml
  - language: !include ../../raml-util/traits/language.raml

resourceTypes:
  - collection: !include ../../raml-util/rtypes/collection.raml
  - collection-item: !include ../../raml-util/rtypes/item-collection.raml
  - get-only: !include ../../raml-util/rtypes/get-only.raml
  - post-empty-body: !include ../../raml-util/rtypes/post-empty-body.raml

/configurations:
  /tables:
    displayName: Configurations
    description:

Retrieve configurations for all modules associated with a specific institution.

Add a module to the configuration tables

The JWT token limits the returned configurations to those of the calling institution
    type:
      collection:
        schemaCollection: configs
        schemaItem: config
        exampleCollection: !include ../_examples/kv_configuration.sample
        exampleItem: !include ../_examples/kv_configuration.sample
    get:
      is: [
        searchable: {description: "with valid searchable fields: for example module = CIRCULATION", example: "{\"module\":\"CIRCULATION\"}"},
        orderable: {fieldsList: "module"},
        pageable
      ]
    /{entryId}:
      displayName: Module configurations
      description:

Delete or Update a specific module from the configuration table
An example of this would be to add a configuration to the circulation table or to delete a configuration from the circulation table. The query parameters can be used to filter for the desired module's configuration

Get a specified module's configurations

The JWT token limits the returned configurations to those of the calling institution
      type:
        collection-item:
          schema: configs
          exampleItem: !include ../_examples/kv_configuration.sample
      get:
        is: [
          searchable: {description: "with valid searchable fields: for example name = renewals_allowed_count", example: "[\"name\", \"renewals_allowed_count\", \"=\"]"},
          orderable: {fieldsList: "module"},
          pageable
        ]

#%RAML 0.8
title: Configurations
version: v1
baseUri: http://github.com/org/folio/lsp-apis
protocols: [ HTTPS ]

documentation:
  - title: Configuration API updating system wide configurations
    content: This documents the API calls that can be made to update configurations in the system

schemas:
  - configs: !include ../_schemas/kv_configurations.schema
  - config: !include ../_schemas/kv_configuration.schema
  - libraries: !include ../_schemas/library.schema

traits:
  - orderable: !include https://raw.githubusercontent.com/folio-org/raml/master/traits/orderable.raml
  - pageable:  !include https://raw.githubusercontent.com/folio-org/raml/master/traits/pageable.raml
  - searchable: !include https://raw.githubusercontent.com/folio-org/raml/master/traits/searchable.raml
  - language: !include https://raw.githubusercontent.com/folio-org/raml/master/traits/language.raml

resourceTypes:
  - collection: !include https://raw.githubusercontent.com/folio-org/raml/master/rtypes/collection.raml
  - collection-item: !include https://raw.githubusercontent.com/folio-org/raml/master/rtypes/item-collection.raml
  - get-only: !include https://raw.githubusercontent.com/folio-org/raml/master/rtypes/get-only.raml
  - post-empty-body: !include https://raw.githubusercontent.com/folio-org/raml/master/rtypes/post-empty-body.raml

/configurations:
  /tables:
    displayName: Configurations
    description:

Retrieve configurations for all modules associated with a specific institution.

Add a module to the configuration tables

The JWT token limits the returned configurations to those of the calling institution
    type:
      collection:
        schemaCollection: configs
        schemaItem: config
        exampleCollection: !include ../_examples/kv_configuration.sample
        exampleItem: !include ../_examples/kv_configuration.sample
    get:
      is: [
        searchable: {description: "with valid searchable fields: for example module = CIRCULATION", example: "{\"module\":\"CIRCULATION\"}"},
        orderable: {fieldsList: "module"},
        pageable
      ]
    /{entryId}:
      displayName: Module configurations
      description:

Delete or Update a specific module from the configuration table
An example of this would be to add a configuration to the circulation table or to delete a configuration from the circulation table. The query parameters can be used to filter for the desired module's configuration

Get a specified module's configurations

The JWT token limits the returned configurations to those of the calling institution
      type:
        collection-item:
          schema: configs
          exampleItem: !include ../_examples/kv_configuration.sample
      get:
        is: [
          searchable: {description: "with valid searchable fields: for example name = renewals_allowed_count", example: "[\"name\", \"renewals_allowed_count\", \"=\"]"},
          orderable: {fieldsList: "module"},
          pageable
        ]


Added missing status descripiton in tracking api


Two more error cases for the RAML

Two more error cases for the RAML

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing

/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  put:
    description: Update descriptor of a particular node, only the name can be changed
    body:
      application/json:
        schema: NodeDescriptor
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: NodeDescriptor
  /{node_id}:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces/{interface_id}:
      get:
        description: Get all modules that provide the specified interface ID
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing

/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  put:
    description: Update descriptor of a particular node, only the name can be changed
    body:
      application/json:
        schema: NodeDescriptor
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: NodeDescriptor
  /{node_id}:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces/{interface_id}:
      get:
        description: Get all modules that provide the specified interface ID
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check