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 examplePOST
orDELETE
) 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, theurl
should reference port0
.
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:
|
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 |