Supported HTTP Methods
The REST service supports three primary HTTP methods for accessing and modifying data in the Traffic Manager configuration system:
•GET
•PUT
•DELETE
GET is used when making read-only requests for a resource, whereas PUT is used when updating existing data or adding new configuration objects. DELETE is used when you wish to completely remove configuration objects from the Traffic Manager.
Each of these methods is discussed in more detail in the sections that follow.
The REST service additionally supports the POST method for uploading files to the Traffic Manager, specifically with respect to configuration backup TAR archive files. For more information, see Configuration Backups.
Requesting a Resource
A client interacts with the Traffic Manager REST API by performing operations on its resources. An operation is distinguished by the HTTP method it uses and the path and query components of the associated URI. Some operations, however, are not applicable to every resource.
The GET method is used to retrieve the current representation of the resource it is used on. It does not alter the resource in any way or have any other side effects.
This is achieved by sending a HTTP GET request to the server with no body. The request must accept a response in JSON format only (by specifying an “Accept” header type of application/json), and authorization is provided using HTTP Basic Auth (for more details, see Authentication). Such a request resembles the following:
GET /api/tm/8.3/config/active/bandwidth/BWClass1 HTTP/1.1
Authorization: Basic YWRtaW46c2VjcmV0MTIz
Accept: application/json
If successful, the server returns a "200 OK" response code with the full resource in the response body. The above Bandwidth class example might produce the following output:
{
"properties": {
"basic": {
"maximum": 10000,
"note": "This is my bandwidth class",
"sharing": "cluster"
}
}
}
This is a JSON structure representing the configuration keys present in the requested bandwidth class object. In this case, it consists of a single "basic" section containing three key:value pairs. Other resource types might contain different or additional sections and corresponding keys.
Setting Configuration for a Resource
This section does not apply to read-only resources such as SNMP counters or system information.
Changing data items in the Traffic Manager configuration system is achieved through a PUT request to a configuration type resource. This applies to either creating new resource items or updating the properties of an existing resource item.
When creating a new resource item, the request URI must contain the full path to the intended item, with the name being the final element of the path. For example, creating a new bandwidth class called "mynewclass" requires using the following URI:
/api/tm/8.3/config/active/bandwidth/mynewclass
For both creation and update operations, the request body must contain a representation of the resource properties in JSON format (with the appropriate body "Content-Type" header set). Partial updates to configuration resources can be performed by only including the properties that need to be altered. Other properties are left unchanged.
For PUT requests, ensure that the request body is encoded as UTF-8.
The REST service returns a "200 OK" response for a correctly updated configuration set, or "201 Created" for establishing a new configuration object of a particular resource type. In these cases, the full resource is returned as the response body. The only exception to this rule is when updating a raw file, which instead returns a "204 No Content" empty-body response.
You might want to exercise some care when creating or updating resources. The changes are permanent and no warning is given for existing configuration that is overridden. If you attempt to create a new resource where one of the same name already exists, you overwrite the properties of the existing record. It is recommended that you build such validation into your REST client application.
Removing Resources
This section does not apply to read-only resources such as SNMP counters or system information.
A HTTP DELETE request for the full URI of a configuration item can be sent to the REST server to permanently remove it. On success, a "204 No Content" empty-body response is returned.