okapi.raml

#%RAML 1.0
title: Okapi Core API
version: 2.0
types:
  DeploymentDescriptor: !include DeploymentDescriptor.json
  LaunchDescriptor: !include LaunchDescriptor.json
  DeploymentDescriptorList: !include DeploymentDescriptorList.json
  ModuleDescriptor: !include ModuleDescriptor.json
  ModuleList: !include ModuleList.json
  InterfaceDescriptor: !include InterfaceDescriptor.json
  InterfaceList: !include InterfaceList.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:
        type: 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:
            type: 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:
            type: 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:
              type: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    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:
        type: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            type: 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:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            type: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  delete:
    description: delete all instances
    responses:
      204:
        description: Ok
        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: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              type: DeploymentDescriptorList
          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 registration for a given instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    /{instance_id}:
      get:
        description: get registration of a specified instance
        responses:
          200:
            body:
              application/json:
                type: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            type: 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:
              type: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                type: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            type: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    put:
      description: Update descriptor of a particular node, only the name can be changed
      body:
        application/json:
          type: NodeDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              type: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              type: 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.
    queryParameters:
      check:
        description: Whether to check dependencies
        type: boolean
        required: false
      preRelease:
        description: whether to allow pre-release modules in dependency check
        type: boolean
        required: false
    body:
      application/json:
        type: 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:
            type: 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:
      dot:
        description: If true, return graphiz DOT content as plain text
        type: boolean
        required: false
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      latest:
        description: limit to latest N releases (most likely 1 if given)
        type: integer
        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
          (default:true).
        type: boolean
        required: false
      npmSnapshot:
        description: whether to include NPM module snapshots
          (default:true).
        type: boolean
        required: false
      provide:
        description: limit to provided interface
        type: string
        required: false
      require:
        description: limit to required interface
        type: string
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            type: ModuleList
          text/plain:
      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:
              type: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          type: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              type: 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:
        type: 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:
            type: 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:
            type: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              type: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          type: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              type: 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:
            type: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                type: 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
        queryParameters:
          full:
            description: whether full or compact MD should be returned
            type: boolean
            required: false
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                type: ModuleList
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{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:
                  type: 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:
              type: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  type: 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:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: Whether the installation is simulated
            type: boolean
            required: false
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
            required: false
          npmSnapshot:
            description: whether to include NPM module snapshots
              (default:true).
            type: boolean
            required: false
          purge:
            description: Disabled modules will also be purged.
            type: boolean
            required: false
          tenantParameters:
            description: Parameters for Tenant init
            type: string
            required: false
        body:
          application/json:
            type: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                type: 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:
          deploy:
            description: whether to deploy (or undeploy if disabling)
            type: boolean
            required: false
          simulate:
            description: whether the upgrade is simulated
            type: boolean
            required: false
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
            required: false
          purge:
            description: Disabled modules will also be purged.
            type: boolean
            required: false
          tenantParameters:
            description: Parameters for Tenant init
            type: string
            required: false
        responses:
          200:
            description: OK
            body:
              application/json:
                type: 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:
      get:
        description: Get all interfaces for tenant
        queryParameters:
          full:
            description: whether brief or full interface list
            type: boolean
            required: false
          type:
            description: limit by interfaceType
            type: string
            required: false
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                type: InterfaceList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{interface_id}:
        get:
          description: Get all modules that provide the specified interface ID
          queryParameters:
            type:
              description: limit by interfaceType
              type: string
              required: false
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  type: 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: Health of modules as seen from proxy
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            type: 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:
        type: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            type: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        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:
        type: 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:
            type: 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:
            type: 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:
              type: 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
        404:
          description: Not Found
          body:
            text/plain:

/_/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