Permalink
Fetching contributors…
Cannot retrieve contributors at this time
976 lines (964 sloc) 26.4 KB
#%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
- 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:
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
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:
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:
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:
schema: 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:
schema: 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:
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
404:
description: Not Found
body:
text/plain:
/{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
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:
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:
/{node_id}:
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
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:
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.
queryParameters:
check:
description: Whether to check dependencies
type: boolean
required: false
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
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:
schema: 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:
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:
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
purge:
description: Disabled modules will also be purged.
type: boolean
required: false
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:
deploy:
description: whether to deploy (or undeploy if disabling)
type: boolean
required: false
simulate:
description: whether the upgrade is simulated
type: boolean
preRelease:
description: Whether pre-releases should be considered for
installation.
type: boolean
purge:
description: Disabled modules will also be purged.
type: boolean
required: false
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:
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:
schema: 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:
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:
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:
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
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