Service Gateway API Overview

Service gateways configure connections between services and Apcera jobs. Apcera includes several built-in service Gateways, including MySQL and Postgres. Apcera provides a simple HTTP-based API that enables you to create custom service gateways.

Overview

A service gateway is composed of two parts:

  • An HTTP server that implements the necessary HTTP endpoints. Apcera makes requests to a service gateway's endpoints to create a new provider, service, or binding.
  • Functionality to manages or provision the service back-end. For example, a service gateway that creates bindings for a MySQL instance will include functionality to connect to and manage a MySQL instance, create users and tables, and so forth.

A service gateway manages the following types of objects:

  • Bindings – Connection information and credentials that allow instances of jobs running within Apcera to reach specific service instances. A binding is constructed from the information about the back-end and state that is maintained by Apcera.

  • Services – A service is a specific instance of a back-end to which jobs may request bindings. For example, a dev_db database on a PostgreSQL dev cluster is represented as a service within the service gateway API. A service back-end can be external to or running within Apcera.

  • Providers – A service gateway's representation of functionality for provisioning services. Examples of providers include a PostgreSQL server, a MySQL cluster, a Redis server, a Memcache pool, the Salesforce API, an Oracle database server, and so forth. Providers may register with compatible service gateways using the API described in this document to augment the types of services available in Apcera.

Service gateway levels

Service Gateways may be as simple as a factory that returns (static) bindings for a web service API, or as complex as necessary to provision new database resources for customer applications. There are two basic levels, or tiers, of service gateway support:

  • Two-tiered service gateways manage bindings and services. They don't create or manage providers.
  • Three-tiered service gateways manage bindings, services, and providers.

A service gateway's methods endpoint (GET /) reports what functionality it supports.

Two-tiered service gateway

For a service gateway that provisions services but does not support multiple providers, additional methods are required:

POST   /services
DELETE /services/:id
POST   /bindings
DELETE /bindings/:id

The corresponding method object returned by the gateway's GET / looks like the following:

{
  "/services": {
    "POST": {}
  },
  "/services/:id": {
    "DELETE": {}
  },
  "/bindings": {
    "POST": {}
  },
  "/bindings/:id": {
    "DELETE": {}
  }
}

Three-tiered service gateway

Service gateways that allow provider registration implement all methods of the service gateway API:

POST   /providers
DELETE /providers/:id
POST   /services
DELETE /services/:id
POST   /bindings
DELETE /bindings/:id

The corresponding method object looks like this:

{
  "/providers": {
    "POST": {}
  },
  "/providers/:id": {
    "DELETE": {}
  },
  "/services": {
    "POST": {}
  },
  "/services/:id": {
    "DELETE": {}
  },
  "/bindings": {
    "POST": {}
  },
  "/bindings/:id": {
    "DELETE": {}
  }
}

Persisting resource state

A service gateway may return the state associated with a particular provider, service or binding to Apcera. Apcera persists the state and attaches it to all subsequent requests that reference the same provider, service or binding. State is shared between Apcera and service gateways using custom HTTP headers: X-Provider-State, X-Service-State, and X-Binding-State.

Note: An earlier version of the Service Gateway API did not provide a persistence mechanism to store resource state and required service gateways to maintain their own data store for this purpose. This "stateful" version of the Service Gateway API is deprecated as of Apcera version 444.2.7.

State data can be any string value the service gateway wants to persist, with the following conditions:

  • Value must be URL-safe, base-64 encoded.
  • Header values are limited to 4kb in length.

As an example, consider when Apcera makes a request to a service gateway to create a new Postgres provider (POST /providers). The request body includes a params object that contains a url field whose value is connection information required to Postgres instance.

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

The service gateway reads the url from the request and confirms it can connect to the instance using its value. It then responds to the request with an X-Provider-State header that contains the same URL:

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"
}

Later, when a user requests a service based on the same Postgres provider, a request is made to the service gateway's POST /services endpoint that includes an X-Provider-State header that contains the same URL.

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"
  }
}

The service gateway uses the URL to connect to the Postgres instance and provision a new database. Its response contains a X-Service-State header that contains the name of the created database:

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

{
  "name": "pgService",
  "description": "Example Postgres service",
  "id": "d4d49461-f2d8-4e43-9cac-b375ee9e89af",
  "provider_id": "1480cdf6-960c-42f5-82dd-323473dba839"
}

In this way, service gateway state is persisted without the service gateway having to maintain a local database. For more information, see the examples in the Service Gateway API Reference.

Creating and deploying a service gateway

The basic steps to create and deploy a service gateway are as follows:

  1. Create an application in your language of choice that defines the necessary HTTP endpoints to support your service, and provides functionality to create providers, services, or bindings, as necessary.
  2. Deploy your application to your Apcera cluster.
  3. Use APC to create providers, services and bindings.

Deploying a service gateway

A service gateway is an Apcera job, so you can deploy it to Apcera using apc.

To deploy a service gateway:

  1. Create a job using apc app create with your service gateway's application
    code.

     $ apc app create my-sg
    
  2. Promote the job to a service gateway using apc gateway promote command.
    This registers the new service type in Apcera.

    $ apc gateway promote my-sg --type my-sg-type
    
  3. The HTTP public route generated for the service gateway job exposes credential information. Remove the route using apc job update

    $ apc job update my-sg --route-delete --url <URL>
    

Your service gateway is ready to be used in Apcera.

Example: Creating a binding

The following steps outline the interaction between Apcera and a service gateway to create a new binding.

  1. Service gateway receives HTTP request from Apcera to POST /bindings.
  2. Service gateway reads provider and service state from the X-Provider-State and X-Service-State HTTP request headers, and information about the new binding from the request body.
  3. Service gateway creates the binding using information from the request body and headers. For example, if the binding is based on a database, the gateway might add a new user to the database, grant them access to a table, and so forth.
  4. Service gateway responds to the HTTP request with the new binding object in the response body and an X-Binding-State header that contains any state information to persist.