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
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
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
- JWT
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
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.