Policy Introduction Policy Syntax Working with Policies Identifying Resources Granting Permissions Default Policies Policy Authoring Tutorial Policy Examples Policy Simulation Global Claims Policy Variables Policy Data Tutorial

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.

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