Service Gateway API Reference

The Service Gateway API reference describes the HTTP endpoints a service gateway implements to manage providers, services, and bindings. For general information about the service gateway API, see the Service Gateway API Overview.

Endpoint Description
GET / Returns methods supported by the service gateway.
POST /providers Creates a new provider.
DELETE /providers/:id Deletes the specified provider.
POST /services Creates a new service.
DELETE /services/:id Deletes the specified service.
POST /bindings Creates a new binding.
DELETE /bindings/:id Deletes the specified binding.

GET /

Exposes the supported HTTP endpoints for the service gateway and any gateway-specific parameters required for those endpoints. Not all service gateways must support all endpoints (see Service Gateway Tiers).

Request Parameters

None.

Response JSON

The response JSON is an object with the following structure:

{
    "/<endpoint>" : {
        "<HTTP-verb>" : <object>
    }
}
  • <endpoint>: A supported HTTP endpoint (for example, /services or /bindings).
  • <HTTP-verb>: The HTTP verb (for example POST or DELETE) to operate on the endpoint.
  • <object>: Defines any service parameters required for the endpoint.

Example

Request:

GET / HTTP 1.1

Response:

{
  "/bindings": {
    "POST": {}
  },
  "/bindings/:id": {
    "DELETE": {}
  },
  "/providers": {
    "POST": {"params": {"url": "mysql://mysqladmin:adminpass@example.com:3306"}}
  },
  "/providers/:id": {
    "DELETE": {}
  },
  "/services": {
    "POST": {"params": {"database": "example_db"}}
  },
  "/services/:id": {
    "DELETE": {}
  }
}

POST /providers

Creates a provider.

Note: Many service gateways don't need to manage providers – in other words, they don't need a provider tier. See Service Gateway Tiers.

Request

The POST body contains a JSON object that describes the provider to create.

Request JSON

Name Type Required Description
name String No Name of the provider to display within Apcera
description String No Extended description of the provider to differentiate similar Providers
type String Yes The service type managed by the provider
params Object No Additional parameters for the provider, defined by the service gateway.

Request Headers

None.

Response

If the provider is created successfully, the service gateway returns an HTTP 200 OK response code and a X-Provider-State header that contains provider state to persist. The response body is a JSON object that describes the newly created provider.

Response JSON

The response JSON object includes the same fields from the request plus, an id field that uniquely identifies the provider to the service gateway.

Name Type Required Description
description String No Extended description of the provider to differentiate similar Providers
id String Yes Uniquely identifies the provider to the service gateway
name String No Name of the provider to display within Apcera
type String Yes The service type managed by the provider

Response Headers

Name Type Required Description
X-Provider-State String No JSON object that contains provider state to persist.

Example

Example request:

POST /providers HTTP/1.1
{
  "name": "Postgres provider",
  "description": "Example Postgres provider",
  "type": "postgres",
  "params": {
    "url": "postgres://postgres:postgres@10.0.167.1:5432"
   }
}

Example response

HTTP/1.1 200 OK
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }

{
  "name": "Postgres provider",
  "description": "Example Postgres provider",
  "id": "1480cdf6-960c-42f5-82dd-323473dba839",
  "type": "postgres"
}

DELETE /providers/:id

Deletes a provider.

Request

The path specifies the ID of the provider to delete.

Request Parameters

Name Type Description
id String A value that uniquely identifies the provider to delete.

Request Headers

None.

Response

If the provided was deleted successfully, the service gateway returns a HTTP/1.1 200 OK response code.

Example

Request:

DELETE /providers/ff3decc3-e61e-420a-9e65-ea5a4b1d37e0

Response:

HTTP/1.1 200 OK

POST /services

Creates a new service.

Request

The request JSON contains information about the new service to create, including a provider_id field, if the service is based upon a provider. Service gateways that manage one or more providers must validate that a meaningful provider_id value is supplied by client requests, or else return a HTTP 400 Bad Request HTTP response.

Request JSON

Name Type Required Description
name String No Name of service to display within Apcera. If a name is not provided, the service gateway should generate a reasonable one and return it in the response.
description String No Extended description of the service
provider_id String No Provider on which the service is provisioned.
params Object No Additional parameters for the service, defined by the service gateway.

Request Headers

Name Type Description
X-Provider-State String JSON object that contains previously persisted state for the provider upon which the service is created.

Response

If the service is created successfully, the service gateway returns an HTTP 200 OK response code and a X-Service-State header that contains any service state to persist. The response body is a JSON object that describes the newly created service. The response JSON object includes the same fields from the request plus, an id field that uniquely identifies the service to the service gateway.

Response JSON

Name Type Required Description
name String No Name of service to display within Apcera.
description String No Extended description of the service
provider_id String No Provider on which the service is provisioned.
params Object No Additional parameters for the service, defined by the service gateway.
status String No Indicates status of the service gateway's request handler. Valid values are "created", "creating", or "errored".
  • created — Indicates the service creation has completed.
  • creating — Indicates that service creation is in progress.
  • errored — Indicates that the service creation has failed.

Response Headers

Name Type Description
X-Provider-State String JSON object that contains state about the provider to persist.

Example

In this example, a request is made for a new service (a database) on a Postgres provider. The database name provided in the request object's params field is returned in the X-Service-State header.

Request:

POST /services HTTP/1.1
Content-Type: application/json
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }
{
  "name": "pgService",
  "description": "Example Postgres service",
  "provider_id": "c7274bea-1310-41d5-984c-36d70c89ac80",
  "params": {
    "database": "898541dcb56749389f071484825035b6"
  }
}

Response:

HTTP/1.1 200 OK
X-Service-State: { "database": "898541dcb56749389f071484825035b6" }

{
  "name": "pgService",
  "description": "Example Postgres service",
  "id": "d4d49461-f2d8-4e43-9cac-b375ee9e89af",
  "provider_id": "c7274bea-1310-41d5-984c-36d70c89ac80"
}

DELETE /services/:id

Request

The path specifies the ID of the binding to delete.

Request parameters

Name Type Description
id String Unique ID of service to delete.
force Boolean Optional. The force parameter may be included in the event that the service provider is no longer available and the service becomes "orphaned".

Request Headers

Name Type Description
X-Provider-State String JSON object that contains previously persisted state for the service's provider.
X-Service-State String JSON object that contains previously persisted state for the service.

Response

A successful response should contain an HTTP/1.1 200 OK response code.

Examples

Example 1: Non-forced delete request:

Request:

DELETE /services/ff3decc3-e61e-420a-9e65-ea5a4b1d37e0
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }
X-Service-State: { "database": "898541dcb56749389f071484825035b6" }

Response:

HTTP/1.1 200 OK
Content-Length: 0

Example 2: Forced delete request:

Request:

DELETE /services/ff3decc3-e61e-420a-9e65-ea5a4b1d37e0?force=true
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }
X-Service-State: { "database": "898541dcb56749389f071484825035b6" }

Response:

HTTP/1.1 200 OK
Content-Length: 0

POST /bindings

Creates a binding URL that provides a job with connectivity to a particular service instance.

Request

Request JSON

Name Type Required Description
name String No Name of the binding to display within Apcera
description String No Extended description of the binding
service_id String Yes Identifies the service to bind to
params Object No Additional parameters for the binding, defined by the service gateway.

Notes:

  • If name is not provided, the service gateway should generate a reasonable one.
  • The params object can include data such as a certificate or other information the service gateway must supply to the back end, to the job, or to a semantic pipeline.

Request Headers

Name Type Description
X-Provider-State String JSON object that contains previously persisted state for the service's provider.
X-Service-State String JSON object that contains previously persisted state for the service for which the binding is requested.

Response

For most bindings the url field returned in the response includes all necessary connection information: host, port, path, user credentials, and scheme. Depending on the service, the URL may be used directly or parsed to separate the data encoded within it. Additional connection parameters may be added to the URL as query parameters, or to the params field as key": "value" pairs of a JSON object.

The port is required and must be set. The port must correspond to a route, so you must add a route before specifying the port. For an application to connect on the port passed through the $PORT environment variable, the url should reference port 0.

The protocol field indicates which semantic pipeline is inserted in the connection between the job and the service.

The url_template field specifies how ephemeral credentials are generated that connect a specific instance of a job to its assigned Semantic Pipeline instance. Service gateways that do not wish to support semantic pipelines do not need to return this field in the response. A template resembles a URL and must include the template tag {{alphanum n}}, where n is an integer from 1-256, inclusive. It may also include one of the modifiers lower or upper after a pipe character | to affect the case of the output. For example: {{alphanum 14 | lower}} will result in a 14-character string consisting of random numbers and lowercase letters. An example url_template value for MySQL service gateway might look like the following:

mysql://{{alphanum 14 | lower}}:{{alphanum 20}}@localhost:3306/an_example_db

Note: Ephemeral credentials are supported by the MySQL and PostgreSQL semantic pipelines. See Ephemeral credentials for details.

Response JSON

Includes all fields from the request, and:

Name Type Required Description
id String Yes Uniquely identifies the binding to the service gateway
url String Yes The connection data for a job to reach the service
url_template String No Controls how Apcera generates ephemeral credentials when a semantic pipeline is present. Not required for services that do not wish to support semantic pipelines.
protocol Object Yes Describes the protocol and protocol version in use by the binding. Contains the following fields:
  • scheme — A string used to match a semantic pipeline to the binding, and may have a different value from the binding object's `url` field.
  • version — A string the specifies the protocol version supported by service. Allows semantic pipelines to handle different versions of the same protocol.

Response Headers

Name Type Description
X-Provider-State String JSON object that contains previously persisted state for the provider upon which the service is based.
X-Service-State String JSON object that contains previously persisted state for the service for which the binding is requested.
X-Binding-State String JSON object that contains state to persist for the binding.

Example

In this example, a binding is requested for the specified Postgres instance (provider) and database (service). In this case, because the service uses a semantic pipeline, the binding that's returned specifies url field that contains the actual credentials the semantic pipeline uses to connect to the database, as well as a url_template field that specifies the format of the generated ephemeral credentials provided to the job.

Request:

POST /bindings HTTP/1.1
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }
X-Service-State: { "database": "898541dcb56749389f071484825035b6" }

{
    "name":"foobar123",
    "service_id":"30955d36-0fab-401b-895a-af910c835e6e",
    "params":{
        "username": "username123", "password": "password123"
    }
}

Response:

HTTP/1.1 200 OK
X-Binding-State: { "username": "username123", "password": password123" }

{
  "name": "foobar123",
  "id": "73754329-6707-4207-8c79-197f83bbe99b",
  "service_id": "30955d36-0fab-401b-895a-af910c835e6e",
  "url": "postgres://R3twMI-iJTqut1kg:UT-xK6SAWbfLZBbY@10.0.167.1:5432/bf977e6d99094afc80e93a62c0c8051b",
  "url_template": "postgres://{{alphanum 16 | lower}}:{{alphanum 16}}@10.0.167.1:5432/bf977e6d99094afc80e93a62c0c8051b",
  "protocol": {
    "scheme": "postgres"
  },
  "params": null
}

DELETE /bindings/:id

Request

The path specifies the ID of the binding to delete.

Request Parameters

Name Type Description
id String Unique ID of binding to delete.

Request Headers

Name Type Description
X-Provider-State String JSON object that contains previously persisted state for the service's provider.
X-Service-State String JSON object that contains previously persisted state for the service for which the binding is requested.
X-Binding-State String JSON object that contains previously persisted state for the binding being deleted.

Example

In this example, the service gateway deletes the database user provided in the X-Binding-State header from the specified database on the specified Postgres provider.

Request:

DELETE /bindings/{id} HTTP 1.1
X-Provider-State: { "url": "postgres://postgres:postgres@10.0.167.1:5432" }
X-Service-State: { "database": "898541dcb56749389f071484825035b6" }
X-Binding-State: { "username": "UgBmn69fNvgAxmP", "password": "UgBmn69fNvgAxmP" }

Response:

HTTP/1.1 200 OK
Content-Length: 0

HTTP status codes

Service gateways use conventional HTTP status codes to indicate success or failure servicing API requests. The following are guidelines for HTTP status codes:

Status Code Reason
200 OK Successful GET, POST, or DELETE. Also used for a POST that doesn't result in a new object
201 Created Response to a POST that results in the creation of a new object
400 Bad Request The request is malformed, such as if the body does not parse or parameters are invalid
401 Unauthorized Authentication information was not provided or invalid
403 Forbidden When authentication succeeded but authenticated user does not have access rights
404 Not Found When a non-existent resource is requested or a URL path is not defined