AMPLIFY Central DevOps APIs

AMPLIFY Central DevOps API

AMPLIFY Central DevOps-friendly APIs allow you to easily integrate AMPLIFY Central with your DevOps process to automate and streamline the deployments of services as API proxies in AMPLIFY Central. To see advanced use cases, AMPLIFY Cli and file examples visit our docs portal.

Each API takes a configuration file, which defines the state of the service you are proxying through AMPLIFY Central. This configuration file is expressed in YAML, and it is used to create, update, and promote an AMPLIFY Central API proxy.

AMPLIFY Central API is based on REST.
HTTP response codes display API errors.
API responses return a JSON file.

Integration with your DevOps process

The source code of your service and the YAML configuration file should reside in the same repository, together with your source control.

When you make changes to the code in your service, you must also update the configuration file with the new state of the API proxy of this service.

Then, you must call the DevOps APIs in your release process to read the configuration file to manage your API proxy.

The updates may define:

The addition of a new API proxy
Changes in an existing API proxy
Changes to authorization policy of an API proxy
Promotion of an existing API proxy from one environment to another, and so on.

The configuration file

AMPLIFY Central DevOps-friendly APIs require a YAML configuration file as an input to define the API configuration in terms of Swagger file, basepath, name, and client authentication. This defines the state of your service.

Currently, there are two versions of configuration file accepted:

v0 - allow to configure front-end authentication policy,
v1 - allow to configure front-end and back-end authentication policies, advanced configuration of created applications, rate limit;

Please see file examples below for more information.

Front-end authentication

Pass-through

Sample configuration file

apiVersion: v1 # This version ensures backward compatibility and would not mandate a frequent update from a client side
proxy:
  name: 'Musical Instruments' # required, name of the proxy (creates a new revision if proxy with this name already exists)
  basePath: /api/v1 # required, base path of the proxy (should be unique)
  swagger: "https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json" # required, swagger url of the proxy
  policy:
    type: pass-through # required, type of client authentication policy
  tags: ["musical", "instruments"] # optional
  team:
    name: "Default Team" # required, the team which the proxy will be assigned to

Api-key authentication

Sample configuration file

apiVersion: v1 # This version ensures backward compatibility and would not mandate a frequent update from a client side
proxy:
    name: 'Musical Instruments' # required, name of the proxy (should be unique)
    basePath: /api/v1 # required, base path of the proxy (should be unique)
    swagger: 'https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json' # required, swagger url of the proxy
    policy:
        type: api-key # required, type of client authentication policy
        app: 'Sample App' # optional, a new app will be created if this is provided
    tags: ['musical', 'instruments'] # optional
    team:
        name: 'Default Team' # required, the team which the proxy will be assigned to

Sample configuration file

apiVersion: v1 # This version ensures backward compatibility and would not mandate a frequent update from a client side
proxy:
    name: 'Musical Instruments' # required, name of the proxy (creates a new revision if proxy with this name already exists)
    basePath: /api/v1 # required, base path of the proxy (should be unique)
    swagger: 'https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json' # required, swagger url of the proxy
    policy:
        type: jwt-token # required, type of client authentication policy
        app: 'Sample App' # optional, a new app will be created if this is provided
    tags: ['musical', 'instruments'] # optional
    team:
        name: 'Default Team' # required, the team which the proxy will be assigned to

Oauth

Sample configuration file

apiVersion: v1 # This version ensures backward compatibility and would not mandate a frequent update from a client side
proxy:
    name: 'Musical Instruments' # required, name of the proxy (creates a new revision if proxy with this name already exists)
    basePath: /api/v1 # required, base path of the proxy (should be unique)
    swagger: 'https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json' # required, swagger url of the proxy
    policy:
        type: oauth # required, type of client authentication policy
        app: 'Sample App' # optional, a new app will be created if this is provided
    tags: ['musical', 'instruments'] # optional
    team:
        name: 'Default Team' # required, the team which the proxy will be assigned to

Key concepts

API proxy

An API proxy represents a back-end API, and it enables API consumers to use your API.

Runtime group

The runtime group is implemented as a group of microgateways running the same API proxies for performance, scalability, and high availability.

Authorize and authenticate with a service account

To authenticate to AMPLIFY Central with a service account, follow these instructions:

Go to AMPLIFY Central and click Service Accounts option.
Create a public/private key-pair and use your public key to create a DevOps Service Account.
Copy the Client ID from the account created (it will look like DOSA_XXXX).
Install the AMPLIFY CLI:

npm i -g @axway/amplify-cli

Note You must have Node.js v8.10 or greater installed.

Use the Client ID previously generated to authenticate:

amplify auth login --realm Broker --json --secret-file /path/to/private_key.pem --client-id <your-service-account-id>

Copy the access_token returned and use it as a bearer token in your API requests:

Bearer <access_token>

Response codes

The response to the requests contains the status code in the response header and any requested data in the response body.

Successful requests return the requested resource, and the return status success code.

Requests to the API can be unsuccessful for many reasons. In all cases, the API returns a status code that displays the nature of the failure with, and a response body containing additional information.

HTTP status code summary

Code	Status	Description
201	Created	A new resource has been created.
400	Bad Request	Fail to validate request parameters.
401	Unauthorized	A valid API key was not provided with the request to authenticate.
403	Forbidden	You do not have access to the requested resource.
404	Not Found	We could not find the specified resource.
409	Conflict	Request conflicts with the current state of the server.
500	Internal Server Error	Unexpected internal server error. Please retry the request.

The code and description of all responses are also described in each method.