api-service-main

API micro-services

This project is a micro-framework to simplify the creation of sophisticated, policy-driven micro-services based on an annotated OpenAPI specification.

Once configured, requests can be served by either a Plugin or an Operation.

• An Operation is middleware that returns a response. It can be bound to one or more OpenAPI resources.

• A Plugin is a strategy - it can be used to serve multiple endpoints - or do something else entirely.

API Endpoints

Most API endpoints are defined by an OpenAPI specification. The Chassis supports OpenAPI (OAS) v3 only.

The configuration uses OpenAPIv3 to define the endpoints and associated middleware operations.

The OpenAPI spec defines the resources, methods, operations and the security policies.

No requests are served by default - a working configuration is required.

The api-service uses a YAML language to describe APIs as configuration file - the OAS definition can be embedded or loaded from a file.

OpenAPI Configuration

In the openapi section of the configuration, we need to specify only the minimum necessary to serve requests.

In the common case that means adding the chassis declaration to an endpoint:

openapi:
  paths:
    /healthz:
      get:
        chassis:
          operationId: api.heartbeat

NOTE: Due to the root openapi key, the normal values are 1-indent deeper than standard OASv3 YAML.

Configuration

The Chassis is driven by the configuration (YAML) file that declares the plugins, the OpenAPI spec and policies.

The chassis incorporates non-functional support for 12-factor applications, logging and auditing.

The chassis loads it's configuration from the ./config folder. Configurations can be specified in JSON or YAML.

The implementation uses the npm config package

First, the chassis loads the default.json/default.yaml file from the ./config folder.

Then it merges the config file that relates to the current NODE_ENV (or "development" if unset)

Minimal Configuration

Each Chassis must be declared with a name and a port. The simplest configuration would be some YAML like this:

    name: Troven-chassis-example
    port: 5005

The logging sub-system captures JSON based log messages that follow a lightweight convention. A log is a system / debug level activity.

    logging:
      file:
        filename: api-service.log

The auditor sub-system captures JSON based audit messages that follow a lightweight convention. An audit is a user-driven activity.

    auditor:
      enabled: true
      file:
        filename: api-service-audit.log

Configuring Features

The basic Chassis can be upgraded using Feature Plugins.

Feature Plugins are installed and initialized when the Chassis starts.

A suite of default plugins are baked-in, new plugins can be easily developed.

To enable a feature, simply configure it by name:

features:
  cors:
    enabled: true
  json:
    enabled: true
  openapi:
    enabled: true

NOTE: Each plugin is enabled by default.

Endpoint Feature

The chassis needs to know how to map an incoming request to a functional endpoint.

Each resource/method in the OpenAPI specification can (and should) be assigned an operation.

For example:

openapi:
  paths:
    /example:
      get:
        operationId: heartbeat_ignored_by_chassis
        chassis
            operationId: api.heartbeat
            message: hello world

The chassis options are augmented at runtime with various parameters.

The chassis.operationId will be used to lookup the feature - not the method's operationId.

Proxy Endpoint

The proxy feature will forward requests to a remote target and return the response.

This is used to expose 3rd party endpoints (internal micro-services, cloud providers, etc) as a simple reverse proxy.

/proxy/healthz:
  get:
    summary: Health check via proxy
      chassis:
        operationId: api.proxy
        target: http://localhost:5005/healthz

Advanced proxy options can be found at http-proxy-middleware.

Note: the defaults used by the chassis are different from the http-proxy-middleware implementation:

 ignorePath: true
 pathRewrite: true
 changeOrigin: true
 xfwd: true

OpenAPI Security

The OAS security policies can be enforced.

The root security policy will be used unless the operation specifies a policy.

openapi:
  security:
    - jwt: [ "example:api:generic" ]
  info:
  paths:

    /healthz:
      get:
        chassis:
          operationId: api.heartbeat
        security:
        - jwt: [ "example:api:heartbeat" ]

The jwt scheme must be defined in components.securitySchemes like this:

components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      description: JWT bearer key to authorize requests.
      bearerFormat: JWT
      name: authorization
      in: header

Current only "http" type and "bearer" scheme are supported at runtime.

TODO: support more schemes, for example: apikey, openid and oauth2

Securing Endpoints

Additional security features are available.

If we want to enforce security before every request, we can do this with the before feature.

With authenticate_jwt, we assert the JWT is valid and signed by the certificateFile.

With authorize_jwt, we match claims against the decoded JWT.

features:
    before:

        authenticate_jwt:
          client_id: test-lab
          certificateFile: ./local/keycloak-public.pem

        authorize_jwt:
          claims:
            iss: https://login.lab.troven.co/auth/realms/Troven

Resolving operationId

The OpenAPI "operationId" is not used by the chassis. It must be unique across all resources.

The Chassis uses the operationId in x-chassis options as the name for the IChassisMiddleware.

If no match is found, the chassis will abort with a fatal error.

The plugins are loaded by the start.js bootstrap file.

For a custom plugin / chassis, you can copy code from api-service-example.

Configuration from Environment

The injection algorithm is simply: remove the prefix, convert to lower case, convert _ to . then treat the result as a JSON path to update the config.

    export APIS_NAME=my-chassis-example
    export APIS_PORT=5005
    export APIS_AUDITOR_ENABLED=true
    export APIS_AUDITOR_FILE_FILENAME=my-chassis.log

At runtime, the chassis will deeply inject the following:

name: "my-chassis-example"
port: 5005
auditor:
    enabled: true
    file:
      filename: "my-chassis.log"

Configuration from external files

This approach allows a standard OpenAPI specification to be reused but augmented with Chassis specific configuration.

It may be used for other purposes - to promote re-use, readability and resilience to change.

If a key ends with the @ symbol - then the value will be used to resolve the values from a File or API.

"openapi@": "./docs/swagger.yaml"
openapi:
  info:
    summary: "My example API"

If a similar key exists - openapi@ and openapi - they are merged.

The remote file from openapi@ is loaded first, then the contents are deep merged with the openapi values.

In this example, the loaded info.summary will be replaced with the inline "My example API".

The merged result is stored into the openapi field in the runtime config.

At runtime, for example in a plugin - the uplifted specification is available as "context.openapi".

Start Example Service

Check out the example:

cd api-service
npm link
cd..
cd api-service-example
npm link api-service
npm install
npm start

Acquiring a Fake JWT

from another terminal, invoke the physical API endpoint:

export FAKE_JWT="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjdG9AYXBpZ2Vla3MuY29tIiwibmFtZSI6IkFQSTpHZWVrcyIsImlhdCI6MTUxNjIzOTAyMiwicm9sZXMiOlsiZXhhbXBsZTphcGk6Z2VuZXJpYyIsImV4YW1wbGU6YXBpOmhlYWx0aHoiLCJleGFtcGxlOmFwaTpzd2FnZ2VyIl19.Xx9hFMLLTCWplmfeQHEkaUUlZTmQ_0dSk0fsxRikNRg"

curl http://localhost:5005/healthz -H "authorization: Bearer $FAKE_JWT"

curl http://localhost:5005/swagger -H "authorization: Bearer $FAKE_JWT"

To create your own synthetic JWT, see https://jwt.io and paste a JWT payload something like this:

{
  "sub": "cto@example.com",
  "name": "Local:Example",
  "iat": 1516239022,
  "roles": [ "example:api:heartbeat" ]
}

The roles field is critical. Roles are used to validate against the scopes from the configured Open API specification.