Introducing REST

REST (REpresentational State Transfer) is a framework for API design. It is based on generic facilities of the standard HTTP protocol, including the six basic HTTP methods (GET, POST, PUT, DELETE, HEAD, INFO) and the full range of HTTP return codes.

A REST interface partitions the API into a series of "resources," each of which can be accessed using one or more HTTP methods. (In the Traffic Manager, only the GET, PUT, and DELETE methods are used; HEAD, POST and INFO are not currently implemented). Each method operates in the Traffic Manager as follows:

•GET: Obtain a representation of the resource, without modifying server state (except perhaps for logging purposes).

•PUT: Create a new resource or apply some change to a resource. Where the resource exists, only those properties specified in the request are modified; all others remain unchanged. If a resource object does not exist, a new one is created.

•DELETE: Delete an existing resource.

Importantly, each resource is uniquely identified with an address, or URI (Uniform Resource Identifier). In other words, if you know the URI you can access the resource (subject to the normal authorization/authentication processes associated with accessing the administrative systems of the Traffic Manager).

Since all resources have URIs, resources can point to other resources by embedding the URIs of related resources within their representations.

In the Traffic Manager, all resources are represented and stored as JSON (JavaScript Object Notation) structures. Requests and responses that interact with the Traffic Manager through the REST API must adopt the same format.

The full range of HTTP return codes is available in REST, although in practice a useful subset can be identified and applied consistently. So, for example, it should be evident from the response itself whether a request has succeeded or not, without any need for parsing the body of the response. However, the Traffic Manager always attempts to provide extra information regarding a failure into the response body. For more details, see Errors.