When an API Proxy is created, this API Proxy does not yet have an access address and is not accessible to clients. When API Proxy is "deployed" on an Environment, a URL of that API Proxy is created according to that Environment and clients can now access API Proxy's methods/endpoints via this URL.
This section describes how to deploy, redeploy and undeploy an API Proxy, as well as create and manage revisions.
Revision and Deployment Status Information
When an API Proxy is selected, the selected revision and deployment status of that API Proxy are displayed in the upper middle part of the screen.
Revisions and deployment operations are carried out through these elements.
A revision is a set of settings and policies applied for an API Proxy. An API Proxy can have multiple revisions. Creating multiple revisions means preparing multiple sets of settings for the same API Proxy.
All revisions of an API Proxy use the same access URL for the same Environment. Therefore, only one revision of an API Proxy can be deployed to an Environment. However, different revisions of the same API Proxy can be deployed simultaneously to different Environments.
The fact that revisions use the same address in the same Environment and that different revisions can run in different Environments makes various scenarios possible. For example, a team that has a Development and a Production Environment opens an API Proxy, which has completed its development and tests, to its customers in the Production environment. While clients are using this API (an API Proxy, which the company has deployed and made available, is now an API for clients), updates should not stop traffic and should not affect the clients. In addition to this, it may also be desirable for the updates to be reversible. In case of any error, it is necessary to immediately move the API to its previous state just before the update. For this, a new revision of the API Proxy is created and updates are made on the new revision. This revision is deployed into the Development Environment (while the previous revision continues to run in the Production Environment) and tests are performed. After the development work is finished, the new revision is uploaded to the Production Environment. This installation takes place instantaneously and the clients start working with the new revision without any interruption. Thus, the maintenance and updating process is carried out transparently. If it is noticed that there is a problem with this revision, it can be returned to the previous revision immediately without disrupting the traffic.
An active revision is the revision that is being worked on.
In the API Proxy interface, the name of the active revision is written in the middle upper part.
When an API Proxy is created, a default revision named Revision 1 is created for that API Proxy.
Listing the Revisions
Clicking on the active revision displays the list of existing revisions.
For each record in the list, there exists the name of the revision, the names of the Environments it is deployed to, creation date, and a button that can be used to create a new revision based on that revision.
Creating a New Revision
In the Revision List, the revision to be taken as a basis for the new revision is determined and the New button on that revision's row is clicked.
A popup appears where the name of the revision to be created and an optional description can be entered. Revision is created by filling in the fields and clicking the Save button.
|Name||It is the name of the revision. It is mandatory and must be unique among all revisions of an API Proxy.|
An optional explanation can be entered for the revision.
Statement of assumptions or points to draw attention to can provide useful information on issues such as which revision was created for what purpose and with what constraints.
When a new revision is created, it becomes the Active Revision and the developer starts working on it. If you want to work on another revision after creating a revision, that revision must be selected first.
Selecting a Revision
In order to select the revision to be worked on, the name of the relevant revision is clicked in the Revision List window. In the example below, if the active revision is Revision 1 and you want to work with Revision 2, it is sufficient to click on the name Revision 2 in the list.
Deleting a Revision
In the Revision List window, it is sufficient to click the (Delete) button on the row of the revision to be deleted.
Click the Compare Revisions link in the Revision List window. In the popup window appeared, the differences of the revisions are displayed after selecting the revisions and clicking the Compare button.
For an API Proxy to be accessible for clients, at least one of its revisions must be deployed to an environment.
The deployment operation deploys the Active Revision. Therefore, in order to upload a certain revision, that revision must first be selected as the Active Revision.
Click the Deploy button next to the Active Revision.
Clicking this button displays the Environments, the installation status of the Active Revision in each Environment, and the Deploy button or the Redeploy and Undeploy buttons depending on its status.
The example below shows that there is only one Environment named prod, the Active Revision is not deployed to (or undeployed from) this Environment yet, and the Deploy button appears.
- A revision can be loaded into one or more Environments.
- Different revisions of an API Proxy can be installed in different Environments.
When the Deploy button is clicked, a popup appears where an optional note about this deployment can be entered. Since these notes will be seen in the deployment history, it is useful to enter a note for each deployment in order to keep track of the deployments.
When the Deploy button is pressed in this window, the Active Revision is deployed into the selected Environment and its status is updated as Deployed. With this update, a separate access URL is created for each of the Environments where this API Proxy is deployed to.
Access URLs of the API Proxy can be seen in the Deployment section of the Overview Tab. In this section, the access URLs for each Environment where API Proxy is installed are displayed on a separate line and the content of the API Definition File at that address can be accessed by clicking the Show Specs link in the Specs column.
The address displayed in the URL column for API Proxy is the root address. The request must be sent to the URL composed by adding the method/endpoint's address to the end of this root address.
Changes made to an already deployed revision are not reflected to clients until that revision is redeployed. This feature allows developers to work without stopping client traffic.When an update is made on an already deployed revision, the button next to the revision turns into Redeploy. This status indicates that a redeployment is required for the updates to take effect.
It is not mandatory to make modifications to redeploy an API Proxy.
Redeployment is also possible from the revision list.
When the Redeploy button is clicked, the process flow is exactly the same as for the deployment.
The reloading process is performed without interruption. Settings made for the reloaded revision replace the previous settings at runtime, and from then on requests are answered according to the new settings.
If an uploaded revision is to be closed for some reason, it is first selected as the Active Revision. Then, by clicking the Deployed button, the dialog that displays the installed Environments opens.
The Undeploy button is clicked on the row of the Environment where the revision is desired to be removed. After the confirmation, this revision is no longer accessible in the selected Environment.
An API Proxy can be deployed, redeployed, and undeployed many times during its lifetime. It is also possible to enter an explanatory note for each operation.
The installation history displays information such as by who, when, which environment this API Proxy was deployed to or undeployed from, and what was the description. To open this window, click on Deployment History button next to the active revision.