AWS Storage Blog
Interacting with the CloudEndure API using Postman
When managing a disaster recovery (DR) project or migration at scale, it can often be time intensive to set up and maintain the necessary infrastructure and settings. Leaning on APIs for automation and scalability can reduce the time cost necessary to manage these efforts. Amazon’s CloudEndure service offers two products that work seamlessly with APIs: CloudEndure Migration and CloudEndure Disaster Recovery.
The CloudEndure user API for both of these products provides a strong set of tools that enables you to interact with your CloudEndure projects in a fast, easily repeated manner at scale. The user API is a RESTful web service. This means that you can interact with it using whichever method you like that allows you to generate HTTP requests. This can be done programmatically, using a language like Python. It can also be done on a more ad hoc basis, using an API client such as Postman, which gives you a graphical user interface (GUI) template for making HTTP requests. This is an easier way of interacting with the API if the user has limited development or programming experience.
In this blog post, I explain how to use Postman to make basic API calls. Postman is a free utility available for macOS, Windows, and Linux. Please follow the link to Postman to learn more about Postman and download it. Postman also provides code snippets in various languages that represent the ad hoc HTTP requests you make using the tool. These allow you to repeat your API interactions easily and introduce your own automation into CloudEndure.
Solution overview
The API calls covered in this post include the following:
- Logging in
- Getting information about a machine
- Changing replication settings
- Changing blueprint settings
These calls represent some common functionality most users want to leverage within the API when working at scale with CloudEndure.
1. Making a login call:
To interact with the API, you must first issue a login call using your API token. This can be found in your CloudEndure console by navigating to a project, then going to Setup and Info and Other Settings.
Example of an API token
Once you’ve located your API token, you can start to construct a login call in Postman. The necessary URL to make the login call is: https://console.cloudendure.com/api/latest/login. Specifically, make a POST request to this location.
Post request to the login URL
As shown, you are issuing a POST request to the URL stated in the preceding documentation page. The next step is to add in the body or payload to the HTTP request. This is done in JSON formatting. Therefore, you must add a header informing Postman to use the application/json type.
Required headers for a login call
There are request samples on the API page that you can use as a skeleton template for your JSON. To add the body, click on Body, then raw. This provides you with a blank space where you can add your payload. Be sure to change the text type to JSON on the right-hand side.
Body of login request, this is where the API token is inserted
All you must do is add your API token where the XXXX-XXXX-... is and then you are ready to send your first request! After you hit send, you should get a response as shown in the following screenshot, which indicates you have been logged in:
200 OK response, with response body showing account details
Notice the status returned is a 200 OK. This indicates a successful login. After logging in, CloudEndure will provide an XSRF-TOKEN as a header. This token can be used for API calls for the next hour before expiring. This prevents you from having to login to make every API call. To find your token from the login call you just completed, you can click on Headers:
Cookie that must be included as a header in future requests
2. Get Machine:
Now let’s say you want to collect some information about a certain machine in CloudEndure. As per the API documentation, this is done through a GET request to the URL:
https://console.cloudendure.com/api/latest/projects/{projectId}/machines/{machineId}
The values for “projectId” and “machineId” come from the URL bar of the machine in the CloudEndure console. You could also get a list of machines using the API if you find that easier. The “get machine” API call must have the x-xsrf-token set as a header, but there is no body or payload required for this API call since we are not changing anything. The request should look like this in Postman:
GET request must include the cookie received from the login call
When you hit Send, you receive a response similar to the following:
CloudEndure returned information about the machine
3. Changing machine replication settings:
Machines in CloudEndure that have a high write rate can require a larger replication server instance type if the default t3.small is not able to keep up with the rate of change. To do this, it is necessary to make a PATCH request to:
To get the value for project id and replicationConfiguration, you can inspect your browser HTTP request when making a similar change in the CloudEndure console GUI. You could also list replication configurations by running a GET request to the following URL:
https://console.cloudendure.com/api/latest/projects/{projectId}/replicationConfigurations
The PATCH request should look something like this in Postman:
PATCH request to change replication configuration
The body of the request requires three values at a minimum:
- ID of the replicationConfiguration (which you received from a previous step).
- Region value of the replicationConfiguration (get this from inspecting browser traffic using developer tools or making a GET replication configurations call).
- Value of the replication server instance type.
The complete request body looks something like this:
Request body to change replication server to t3.large
The response back confirms that the change has been made:
200 OK response indicating the change has been made
It can be seen that the "replicationServerType” value has been changed to t3.large as requested. A similar pattern could be used to change any of the replication settings for this machine.
4. Updating a blueprint:
Updating a blueprint uses the same type of logic and sequence of API calls as updating replication settings.
It is necessary to issue a PATCH call to:
https://console.cloudendure.com/api/latest/projects/{projectId}/blueprints/{blueprintId}
To get the values, list all of the blueprints in the project by using a GET call to:
https://console.cloudendure.com/api/latest/projects/{projectId}/blueprints
This allows you to get a “blueprintId” to use in your PATCH call.
Your PATCH request will look something like this:
PATCH request body to update blueprint to m5.large instance type
This example shows a change in the “instanceType” to “m5.large". The other values are required in order to update the blueprint. You could swap out “instanceType” with any other blueprint field, or you could make multiple changes to the blueprint in one API call by extending your JSON to include other fields. When you successfully change the blueprint, you get a response like the following:
The response status shows a value of 200 OK and the request fields are updated
Please keep in mind that the changes we have made are now saved in your CloudEndure project. If the changes were done as a test or proof of concept, remember to revert the changes back to the previous settings to avoid incurring unwanted costs.
Conclusion:
In this blog post, I covered the basic steps on how to make a few important API calls. Using the CloudEndure API is very helpful for managing large projects at scale, and for creating easy to follow procedures for your migration or DR team. Once you have a template for making your desired changes in Postman, it is easy to share this out to the rest of your DR or Migration management team. This way, you can have easily repeatable workflows for managing your projects at scale.
I encourage all users to review the API documentation to find the API calls that will be most helpful to them. Thanks for reading this blog post. If you have any comments or questions, feel free to share them in the comment section.