Okapi Core API (2.0)

Table of contents

/_/deployment/modules

Deployment service. This is responsible for starting and stopping modules.

POST /_/deployment/modules

Deploy (launch process, start a container, etc) instance of a particular service, according to the deployment descriptor.

POST /_/deployment/modules
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 201

Created

Headers
  • Location: required (string)

    URI to the descriptor of the deployed instance

  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/deployment/modules

List all deployed instances

GET /_/deployment/modules

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptorList",
  "description": "Deployment information list",
  "type": "array",
  "items": {
    "$ref": "DeploymentDescriptor.json"
  }
}

GET /_/deployment/modules/{instance_id}

Retrieve deployment descriptor for a particular instance

GET /_/deployment/modules/{instance_id}
URI Parameters
  • instance_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

DELETE /_/deployment/modules/{instance_id}

Shutdown instance

DELETE /_/deployment/modules/{instance_id}
URI Parameters
  • instance_id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

/_/discovery/modules

Discovery service. This is responsible for monitoring all instances (deployed) on, possibly many, deployment nodes.

POST /_/discovery/modules

Register instance under a specified service id

POST /_/discovery/modules
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 201

Created

Headers
  • Location: required (string)

    URI to the registered instance

  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/discovery/modules

Return all instances

GET /_/discovery/modules

Response 200

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptorList",
  "description": "Deployment information list",
  "type": "array",
  "items": {
    "$ref": "DeploymentDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

DELETE /_/discovery/modules

Delete all instances

DELETE /_/discovery/modules

Response 204

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/discovery/modules/{service_id}

List all instances for a particular service

GET /_/discovery/modules/{service_id}
URI Parameters
  • service_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptorList",
  "description": "Deployment information list",
  "type": "array",
  "items": {
    "$ref": "DeploymentDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

DELETE /_/discovery/modules/{service_id}

Remove registration for a given instance

DELETE /_/discovery/modules/{service_id}
URI Parameters
  • service_id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 404

Not Found

Body

Media type: text/plain

Type: any

GET /_/discovery/modules/{service_id}/{instance_id}

Get registration of a specified instance

GET /_/discovery/modules/{service_id}/{instance_id}
URI Parameters
  • service_id: required (string)
  • instance_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "DeploymentDescriptor",
  "description" : "Module deployment information. There are two modes: deployment managed by Okapi (with nodeId specified) and remote module (with URL specified).",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "The Module ID for the instance",
      "type": "string"
    },
    "instId": {
       "description": "Instance ID (at least unique for node)",
       "type": "string"
    },
    "nodeId": {
      "description": "Node ID where module is deployed",
      "type": ["string", "null"]
    },
    "url": {
      "description": "URL where module is deployed (not managed by Okapi)",
      "type": ["string", "null"]
    },
    "descriptor" : {
      "description": "Deployment details",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["srvcId"]
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

DELETE /_/discovery/modules/{service_id}/{instance_id}

Remove registration for a given instance

DELETE /_/discovery/modules/{service_id}/{instance_id}
URI Parameters
  • service_id: required (string)
  • instance_id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 404

Not Found

Body

Media type: text/plain

Type: any

/_/discovery/health

Health service for individual instances

GET /_/discovery/health

Get health info for all services

GET /_/discovery/health

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "HealthDescriptorList",
  "description": "List of health descriptors",
  "type": "array",
  "items": {
    "$ref": "HealthDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/discovery/health/{service_id}

Health for all instances for a particular service

GET /_/discovery/health/{service_id}
URI Parameters
  • service_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "HealthDescriptorList",
  "description": "List of health descriptors",
  "type": "array",
  "items": {
    "$ref": "HealthDescriptor.json"
  }
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

GET /_/discovery/health/{service_id}/{instance_id}

Get health for a particular instance

GET /_/discovery/health/{service_id}/{instance_id}
URI Parameters
  • service_id: required (string)
  • instance_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "HealthDescriptor",
  "description": "Health for an instance",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "srvcId": {
      "description": "Service ID, normally same as Module ID",
      "type": "string"
    },
    "instId": {
      "description": "Instance ID, unique on node",
      "type": "string"
    },
    "healthMessage": {
      "description": "Health message",
      "type" : "string"
    },
    "healthStatus": {
      "description": "Whether healthy",
      "type" : "boolean"
    }
  },
  "required": ["srvcId", "instId", "healthMessage", "healthStatus"]
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

/_/discovery/nodes

Get information about nodes

GET /_/discovery/nodes

Get list of all nodes

GET /_/discovery/nodes

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "NodeDescriptorList",
  "description": "List of Nodes",
  "type": "array",
  "items": {
    "$ref": "NodeDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

PUT /_/discovery/nodes/{node_id}

Update descriptor of a particular node, only the name can be changed

PUT /_/discovery/nodes/{node_id}
URI Parameters
  • node_id: required (string)
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "NodeDescriptor",
  "description": "Deployment node information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "nodeId": {
      "description": "Node ID",
      "type": "string"
    },
    "url": {
      "description": "Host:port for for this node",
      "type": "string"
    },
    "nodeName": {
      "description": "Human readable node name",
      "type": "string"
    }
  },
  "required": ["nodeId", "url"]
}

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "NodeDescriptor",
  "description": "Deployment node information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "nodeId": {
      "description": "Node ID",
      "type": "string"
    },
    "url": {
      "description": "Host:port for for this node",
      "type": "string"
    },
    "nodeName": {
      "description": "Human readable node name",
      "type": "string"
    }
  },
  "required": ["nodeId", "url"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/discovery/nodes/{node_id}

Get info for one node

GET /_/discovery/nodes/{node_id}
URI Parameters
  • node_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "NodeDescriptor",
  "description": "Deployment node information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "nodeId": {
      "description": "Node ID",
      "type": "string"
    },
    "url": {
      "description": "Host:port for for this node",
      "type": "string"
    },
    "nodeName": {
      "description": "Human readable node name",
      "type": "string"
    }
  },
  "required": ["nodeId", "url"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

/_/proxy/modules

Proxy modules service

POST /_/proxy/modules

Announce new module to the proxy. Once successful a module can be selected for a specific tenant.

POST /_/proxy/modules
Query Parameters
  • check: (boolean)

    Whether to check dependencies

  • preRelease: (boolean)

    Whether to allow pre-release modules in dependency check

  • npmSnapshot: (boolean)

    Whether to allow NPM module snapshots in dependency check default: true

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleDescriptor",
  "description": "A FOLIO Module",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID with format product-semver",
      "type": "string"
    },
    "name": {
      "description": "Short name for module (does not include version)",
      "type": "string"
    },
    "replaces": {
      "description": "List of modules that this replaces",
      "type": "array",
      "items": {
        "description": "Module name - without semantic version",
        "type": "string"
      }
    },
    "tags" : {
      "description": "Module tags",
      "type" : ["array", "null"],
      "items" : {
        "description": "Module tag",
        "type": "string"
      }
    },
    "requires": {
      "description": "Required interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "provides": {
      "description": "Provided interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceDescriptor.json"
      }
    },
    "optional": {
      "description": "Optional interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "filters": {
      "description": "Provided filters",
      "type": "array",
      "items": {
        "$ref": "RoutingEntry.json"
      }
    },
    "permissionSets": {
      "description": "Module Permission Sets",
      "type": ["array", "null"],
      "items": {
        "$ref": "Permission.json"
      }
    },
    "env" : {
      "description": "Supported environment variables",
      "$ref" : "EnvEntryList.json"
    },
    "metadata" : {
      "description": "Module Metadata (any object)",
      "type" : "object"
    },
    "uiDescriptor": {
      "description": "UI module descriptor",
      "$ref": "UiModuleDescriptor.json"
    },
    "launchDescriptor": {
      "description": "Default deployment for this module",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["id"]
}

Response 201

Created

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

  • Location: required (string)

    URI to the created module instance

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleDescriptor",
  "description": "A FOLIO Module",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID with format product-semver",
      "type": "string"
    },
    "name": {
      "description": "Short name for module (does not include version)",
      "type": "string"
    },
    "replaces": {
      "description": "List of modules that this replaces",
      "type": "array",
      "items": {
        "description": "Module name - without semantic version",
        "type": "string"
      }
    },
    "tags" : {
      "description": "Module tags",
      "type" : ["array", "null"],
      "items" : {
        "description": "Module tag",
        "type": "string"
      }
    },
    "requires": {
      "description": "Required interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "provides": {
      "description": "Provided interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceDescriptor.json"
      }
    },
    "optional": {
      "description": "Optional interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "filters": {
      "description": "Provided filters",
      "type": "array",
      "items": {
        "$ref": "RoutingEntry.json"
      }
    },
    "permissionSets": {
      "description": "Module Permission Sets",
      "type": ["array", "null"],
      "items": {
        "$ref": "Permission.json"
      }
    },
    "env" : {
      "description": "Supported environment variables",
      "$ref" : "EnvEntryList.json"
    },
    "metadata" : {
      "description": "Module Metadata (any object)",
      "type" : "object"
    },
    "uiDescriptor": {
      "description": "UI module descriptor",
      "$ref": "UiModuleDescriptor.json"
    },
    "launchDescriptor": {
      "description": "Default deployment for this module",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["id"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/modules

List all or subset of modules for proxy

GET /_/proxy/modules
Query Parameters
  • dot: (boolean)

    If true, return Graphviz DOT content as plain text

  • filter: (string)

    Filter by module ID

  • full: (boolean)

    Whether full or compact MD should be returned

  • latest: (integer)

    Limit to latest N releases (most likely 1 if given)

  • npmSnapshot: (boolean)

    Whether to include NPM module snapshots (default:true).

  • order: (one of desc, asc)

    Order

  • orderBy: (string)

    Order by field

  • preRelease: (boolean)

    Whether to include modules with pre-release info (default:true).

  • provide: (string)

    Limit to provided interface

  • require: (string)

    Limit to required interface

  • scope: (string)

    Limit to interface scope (only useful with provide and require)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleList",
  "description": "List of Module Descriptors",
  "type": "array",
  "items": {
    "$ref": "ModuleDescriptor.json"
  }
}

Media type: text/plain

Type: any

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/modules/{module_id}

Retrieve descriptor for a particular module

GET /_/proxy/modules/{module_id}
URI Parameters
  • module_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleDescriptor",
  "description": "A FOLIO Module",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID with format product-semver",
      "type": "string"
    },
    "name": {
      "description": "Short name for module (does not include version)",
      "type": "string"
    },
    "replaces": {
      "description": "List of modules that this replaces",
      "type": "array",
      "items": {
        "description": "Module name - without semantic version",
        "type": "string"
      }
    },
    "tags" : {
      "description": "Module tags",
      "type" : ["array", "null"],
      "items" : {
        "description": "Module tag",
        "type": "string"
      }
    },
    "requires": {
      "description": "Required interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "provides": {
      "description": "Provided interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceDescriptor.json"
      }
    },
    "optional": {
      "description": "Optional interfaces",
      "type": ["array", "null"],
      "items": {
        "$ref": "InterfaceReference.json"
      }
    },
    "filters": {
      "description": "Provided filters",
      "type": "array",
      "items": {
        "$ref": "RoutingEntry.json"
      }
    },
    "permissionSets": {
      "description": "Module Permission Sets",
      "type": ["array", "null"],
      "items": {
        "$ref": "Permission.json"
      }
    },
    "env" : {
      "description": "Supported environment variables",
      "$ref" : "EnvEntryList.json"
    },
    "metadata" : {
      "description": "Module Metadata (any object)",
      "type" : "object"
    },
    "uiDescriptor": {
      "description": "UI module descriptor",
      "$ref": "UiModuleDescriptor.json"
    },
    "launchDescriptor": {
      "description": "Default deployment for this module",
      "$ref": "LaunchDescriptor.json"
    }
  },
  "required": ["id"]
}

DELETE /_/proxy/modules/{module_id}

Remove module descriptor for a particular module, module will no longer be selectable by tenants

DELETE /_/proxy/modules/{module_id}
URI Parameters
  • module_id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

/_/proxy/tenants

Tenants service

POST /_/proxy/tenants

Create a new tenant

POST /_/proxy/tenants
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantDescriptor",
  "description": "Tenant information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Tenant ID",
      "type": "string"
    },
    "name": {
      "description": "Tenant name",
      "type": "string"
    },
    "description": {
      "description": "Tenant description",
      "type": "string"
    }
  }
}

Response 201

Tenant has been created

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

  • Location: required (string)

    URI to the created tenant

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantDescriptor",
  "description": "Tenant information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Tenant ID",
      "type": "string"
    },
    "name": {
      "description": "Tenant name",
      "type": "string"
    },
    "description": {
      "description": "Tenant description",
      "type": "string"
    }
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

GET /_/proxy/tenants

List all tenants

GET /_/proxy/tenants

Response 200

List of tenants in a brief format

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantList",
  "description": "List of Tenants",
  "type": "array",
  "items": {
    "$ref": "TenantDescriptor.json"
  }
}

GET /_/proxy/tenants/{tenant_id}

Retrieve a tenant

GET /_/proxy/tenants/{tenant_id}
URI Parameters
  • tenant_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantDescriptor",
  "description": "Tenant information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Tenant ID",
      "type": "string"
    },
    "name": {
      "description": "Tenant name",
      "type": "string"
    },
    "description": {
      "description": "Tenant description",
      "type": "string"
    }
  }
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

PUT /_/proxy/tenants/{tenant_id}

Update a tenant

PUT /_/proxy/tenants/{tenant_id}
URI Parameters
  • tenant_id: required (string)
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantDescriptor",
  "description": "Tenant information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Tenant ID",
      "type": "string"
    },
    "name": {
      "description": "Tenant name",
      "type": "string"
    },
    "description": {
      "description": "Tenant description",
      "type": "string"
    }
  }
}

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantDescriptor",
  "description": "Tenant information",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Tenant ID",
      "type": "string"
    },
    "name": {
      "description": "Tenant name",
      "type": "string"
    },
    "description": {
      "description": "Tenant description",
      "type": "string"
    }
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

DELETE /_/proxy/tenants/{tenant_id}

Remove a tenant

DELETE /_/proxy/tenants/{tenant_id}
URI Parameters
  • tenant_id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 403

Forbidden

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

POST /_/proxy/tenants/{tenant_id}/modules

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.

POST /_/proxy/tenants/{tenant_id}/modules
URI Parameters
  • tenant_id: required (string)
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptor",
  "description": "Module transitions",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID (or just product part)",
      "type": "string"
    },
    "from": {
      "description": "Original Module ID when transitioning from one module to another",
      "type": "string"
    },
    "action" : {
      "description": "Module action",
      "type" : "string",
      "enum" : [ "enable", "disable", "uptodate", "suggest", "conflict" ]
    },
    "message": {
      "description": "Diagnostic Message",
      "type": "string"
    }
  },
  "required" : ["id"]
}

Response 201

Created

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

  • Location: required (string)

    URI to the enabled module

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptor",
  "description": "Module transitions",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID (or just product part)",
      "type": "string"
    },
    "from": {
      "description": "Original Module ID when transitioning from one module to another",
      "type": "string"
    },
    "action" : {
      "description": "Module action",
      "type" : "string",
      "enum" : [ "enable", "disable", "uptodate", "suggest", "conflict" ]
    },
    "message": {
      "description": "Diagnostic Message",
      "type": "string"
    }
  },
  "required" : ["id"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/tenants/{tenant_id}/modules

Get enabled modules for tenant

GET /_/proxy/tenants/{tenant_id}/modules
URI Parameters
  • tenant_id: required (string)
Query Parameters
  • dot: (boolean)

    If true, return Graphviz DOT content as plain text

  • filter: (string)

    Filter by module ID

  • full: (boolean)

    Whether full or compact MD should be returned

  • latest: (integer)

    Limit to latest N releases (most likely 1 if given)

  • npmSnapshot: (boolean)

    Whether to include NPM module snapshots (default:true).

  • order: (one of desc, asc)

    Order

  • orderBy: (string)

    Order by field

  • preRelease: (boolean)

    Whether to include modules with pre-release info (default:true).

  • provide: (string)

    Limit to provided interface

  • require: (string)

    Limit to required interface

  • scope: (string)

    Limit to interface scope (only useful with provide and require)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleList",
  "description": "List of Module Descriptors",
  "type": "array",
  "items": {
    "$ref": "ModuleDescriptor.json"
  }
}

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

DELETE /_/proxy/tenants/{tenant_id}/modules

Disable modules for tenant

DELETE /_/proxy/tenants/{tenant_id}/modules
URI Parameters
  • tenant_id: required (string)
Query Parameters
  • invoke: (boolean)

    Whether to invoke for tenant init/permissions/purge (default: true).

  • purge: (boolean)

    Disabled modules will also be purged.

  • tenantParameters: (string)

    Parameters for Tenant init

Response 204

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/tenants/{tenant_id}/modules/{module_id}

Look up particular module selection

GET /_/proxy/tenants/{tenant_id}/modules/{module_id}
URI Parameters
  • tenant_id: required (string)
  • module_id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptor",
  "description": "Module transitions",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID (or just product part)",
      "type": "string"
    },
    "from": {
      "description": "Original Module ID when transitioning from one module to another",
      "type": "string"
    },
    "action" : {
      "description": "Module action",
      "type" : "string",
      "enum" : [ "enable", "disable", "uptodate", "suggest", "conflict" ]
    },
    "message": {
      "description": "Diagnostic Message",
      "type": "string"
    }
  },
  "required" : ["id"]
}

Response 404

Not Found

Body

Media type: text/plain

Type: any

POST /_/proxy/tenants/{tenant_id}/modules/{module_id}

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.

POST /_/proxy/tenants/{tenant_id}/modules/{module_id}
URI Parameters
  • tenant_id: required (string)
  • module_id: required (string)
Query Parameters
  • invoke: (boolean)

    Whether to invoke for tenant init/permissions/purge (default: true).

  • purge: (boolean)

    Disabled modules will also be purged.

  • tenantParameters: (string)

    Parameters for Tenant init

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptor",
  "description": "Module transitions",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID (or just product part)",
      "type": "string"
    },
    "from": {
      "description": "Original Module ID when transitioning from one module to another",
      "type": "string"
    },
    "action" : {
      "description": "Module action",
      "type" : "string",
      "enum" : [ "enable", "disable", "uptodate", "suggest", "conflict" ]
    },
    "message": {
      "description": "Diagnostic Message",
      "type": "string"
    }
  },
  "required" : ["id"]
}

Response 201

Created

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

  • Location: required (string)

    URI to the enabled module

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptor",
  "description": "Module transitions",
  "type": "object",
  "additionalProperties" : false,
  "properties": {
    "id": {
      "description": "Module ID (or just product part)",
      "type": "string"
    },
    "from": {
      "description": "Original Module ID when transitioning from one module to another",
      "type": "string"
    },
    "action" : {
      "description": "Module action",
      "type" : "string",
      "enum" : [ "enable", "disable", "uptodate", "suggest", "conflict" ]
    },
    "message": {
      "description": "Diagnostic Message",
      "type": "string"
    }
  },
  "required" : ["id"]
}

Response 400

Client Error

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

DELETE /_/proxy/tenants/{tenant_id}/modules/{module_id}

Disable a module for a tenant. This call will eventually be replaced by the 'install' service.

DELETE /_/proxy/tenants/{tenant_id}/modules/{module_id}
URI Parameters
  • tenant_id: required (string)
  • module_id: required (string)
Query Parameters
  • invoke: (boolean)

    Whether to invoke for tenant init/permissions/purge (default: true).

  • purge: (boolean)

    Disabled modules will also be purged.

  • tenantParameters: (string)

    Parameters for Tenant init

Response 204

Gone

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 400

Client Error

Body

Media type: text/plain

Type: any

POST /_/proxy/tenants/{tenant_id}/install

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 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.

POST /_/proxy/tenants/{tenant_id}/install
URI Parameters
  • tenant_id: required (string)
Query Parameters
  • deploy: (boolean)

    Whether to deploy (or undeploy if disabling)

  • invoke: (boolean)

    Whether to invoke for tenant init/permissions/purge (default: true).

  • npmSnapshot: (boolean)

    Whether to include NPM module snapshots (default:true).

  • preRelease: (boolean)

    Whether pre-releases should be considered for installation.

  • purge: (boolean)

    Disabled modules will also be purged.

  • simulate: (boolean)

    Whether the installation is simulated

  • tenantParameters: (string)

    Parameters for Tenant init

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptorList",
  "description": "List of module transitions",
  "type": "array",
  "items": {
    "$ref": "TenantModuleDescriptor.json"
  }
}

Response 200

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptorList",
  "description": "List of module transitions",
  "type": "array",
  "items": {
    "$ref": "TenantModuleDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

POST /_/proxy/tenants/{tenant_id}/upgrade

Check if newer modules exist, and upgrade for tenant. The response is a list of modules that should be enabled, disabled or upgraded to perform the upgrade.

POST /_/proxy/tenants/{tenant_id}/upgrade
URI Parameters
  • tenant_id: required (string)
Query Parameters
  • deploy: (boolean)

    Whether to deploy (or undeploy if disabling)

  • invoke: (boolean)

    Whether to invoke for tenant init/permissions/purge (default: true).

  • preRelease: (boolean)

    Whether pre-releases should be considered for installation.

  • purge: (boolean)

    Disabled modules will also be purged.

  • simulate: (boolean)

    Whether the upgrade is simulated

  • tenantParameters: (string)

    Parameters for Tenant init

Response 200

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptorList",
  "description": "List of module transitions",
  "type": "array",
  "items": {
    "$ref": "TenantModuleDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/tenants/{tenant_id}/interfaces

Get all interfaces for tenant

GET /_/proxy/tenants/{tenant_id}/interfaces
URI Parameters
  • tenant_id: required (string)
Query Parameters
  • full: (boolean)

    Whether brief or full interface list

  • type: (string)

    Limit by interfaceType

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "InterfaceList",
  "description": "Interface List",
  "type": "array",
  "items": {
    "$ref": "InterfaceDescriptor.json"
  }
}

Response 400

Client Error

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/proxy/tenants/{tenant_id}/interfaces/{interface_id}

Get all modules that provide the specified interface ID DEPRECATED. Use /_/proxy/tenants/{tenant_id}/modules?provide={interface_id} instead

GET /_/proxy/tenants/{tenant_id}/interfaces/{interface_id}
URI Parameters
  • tenant_id: required (string)
  • interface_id: required (string)
Query Parameters
  • type: (string)

    Limit by interfaceType

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "TenantModuleDescriptorList",
  "description": "List of module transitions",
  "type": "array",
  "items": {
    "$ref": "TenantModuleDescriptor.json"
  }
}

Response 400

Client Error

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

/_/proxy/health

Health of modules as seen from proxy

GET /_/proxy/health

Check health of modules

GET /_/proxy/health

Response 200

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "HealthStatusList",
  "description": "Health for each module as seen from proxy",
  "type": "array",
  "items": {
    "$ref": "HealthStatus.json"
  }
}

Response 500

Server Error

/_/proxy/pull/modules

Pull module descriptors from a remote repository

POST /_/proxy/pull/modules

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.

POST /_/proxy/pull/modules
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PullDescriptor",
  "description": "Information controlling the pull facility",
  "type": "object",
  "properties": {
    "urls": {
      "description": "List of URLs from which Okapi attempts pulling",
      "type": "array",
      "items" : {
         "type" : "string"
      }
    }
  }
}

Response 200

OK

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "ModuleList",
  "description": "List of Module Descriptors",
  "type": "array",
  "items": {
    "$ref": "ModuleDescriptor.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

/_/env

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

Add environment entry

POST /_/env
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "EnvEntry",
  "description": "Environment Variable",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "description": "Key",
      "type": "string"
    },
    "value": {
      "description": "Value",
      "type": "string"
    },
    "description": {
      "description": "Description",
      "type": "string"
    }
  },
  "required": ["name"]
}

Response 201

Created

Headers
  • Location: required (string)

    URI to the environment entry instance

  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "EnvEntry",
  "description": "Environment Variable",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "description": "Key",
      "type": "string"
    },
    "value": {
      "description": "Value",
      "type": "string"
    },
    "description": {
      "description": "Description",
      "type": "string"
    }
  },
  "required": ["name"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/env

Get list of all environment variables

GET /_/env

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "EnvEntryList",
  "description": "List of environment variables",
  "type": "array",
  "items": {
    "$ref": "EnvEntry.json"
  }
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

GET /_/env/{id}

Get info for one environment variable

GET /_/env/{id}
URI Parameters
  • id: required (string)

Response 200

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "EnvEntry",
  "description": "Environment Variable",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "description": "Key",
      "type": "string"
    },
    "value": {
      "description": "Value",
      "type": "string"
    },
    "description": {
      "description": "Description",
      "type": "string"
    }
  },
  "required": ["name"]
}

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 404

Not Found

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

DELETE /_/env/{id}

Remove environment variable

DELETE /_/env/{id}
URI Parameters
  • id: required (string)

Response 204

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Response 404

Not Found

Body

Media type: text/plain

Type: any

/_/version

Service for getting information about Okapi

GET /_/version

Get Okapi version

GET /_/version

Response 200

OK, with version in body

Headers
  • X-Okapi-Trace: required (string)

    Okapi trace and timing

Body

Media type: text/plain

Type: any

Response 400

Bad Request

Body

Media type: text/plain

Type: any

Response 500

Server Error

Body

Media type: text/plain

Type: any

/_/invoke/tenant/{id}

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 /_/invoke/tenant/{id}

Invoke any service (the rest of the path, any method, any response).

GET /_/invoke/tenant/{id}
URI Parameters
  • id: required (string)

Response 200

OK

Body

Media type: text/plain

Type: any