AMPLIFY Central DevOps APIs

{$$.env.product_name} DevOps API

{$$.env.product_name} DevOps-friendly APIs allow you to easily integrate {$$.env.product_name} with your DevOps process to automate and streamline the deployments of services as API proxies in {$$.env.product_name}.

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

{$$.env.product_name} 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

{$$.env.product_name} 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.

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' # name of the proxy
    basePath: /api/v1 # base path of the proxy
    swagger: 'https://ec062a054a2977120b7e721801edb38ca24dfbb3.cloudapp-enterprise.appcelerator.com/apidoc/swagger.json' # optional. Swagger url of the proxy
    policy:
        type: api-key # type of client authentication policy: can be pass-through or api-key
        app: 'Sample App' # optional if policy type is pass-through
    tags: ['musical', 'instruments'] # optional
    team: # the team which the proxy will be assigned to.
        name: 'Default Team'

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 {$$.env.product_name} with a service account, follow these instructions:

Go to {$$.env.product_name} 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.