{$$.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
    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
        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.