REST

AT&T Cloud Architect provides a RESTful API in addition to SOAP and XML-RPC style API services. Use the REST API in cases where your programming language may not have good SOAP or XML-RPC support but can perform simple HTTP protocol actions and can interpret XML or JSON data.

REST URLs

REST API URLs are structured to easily traverse AT&T Cloud Architect's object hierarchy. A basic REST request is structured as follows:

https://[username]:[apiKey]@api.[service.]attcloudarchitect.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • All REST requests, even private network requests, must be passed through HTTP SSL.
  • Use your API username and key to authenticate your request through HTTP authentication.
  • The base hostname and folder name for a REST request is either api.attcloudarchitect.com/rest/v3/ or api.service.attcloudarchitect.com/rest/v3/. Use api.service.attcloudarchitect.com/rest/v3/ to access the REST API over AT&T Cloud Architect's private network. It's a more secure way to communicate with AT&T Cloud Architect, but the system making API calls must be on AT&T Cloud Architect's private network (either purchased from AT&T Cloud Architect or logged into AT&T Cloud Architect's private network VPN).
  • Follow up the base URL with the name of the API service you wish to call, for instance "Account" or "Hardware_Server".
  • If your API request requires an initialization parameter, add a slash followed by your init parameter ID to your URL.
  • The AT&T Cloud Architect REST API can return either XML or JSON formatted output. Add ".xml" or ".json" to the end of your request to specify which format you'd like to receive data in.

A request like this calls the getObject() method of the API service you're trying to call. Account::getObject doesn't require an initialization parameter, so its REST URL looks like this:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account.json

However, to call the getObject() method for a specific Hardware_Server record use the following URL, assuming "1234" is the ID of the server you wish to retrieve:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Hardware_Server/1234.json

Call API methods other than getObject() by placing the method's name after your initialization parameter. If your method begins with "get", remove the word "get" from the method name and convert its first letter to uppercase. This method can also be used to quickly access an object's relational properties. For instance, the getHardware() method and hardware relational property in the Account API service can be reached at:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/Hardware.json

Similarly, a server's network components can be reached at the following URL:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Hardware_Server/1234/NetworkComponents.json

Chain a combination of initialization parameter IDs and relational properties to drill down into specific object components. Every ID added will drill into that specific relational property. For instance, if you wish to get server 1234's network component with ID 5678 use the URL:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Hardware_Server/1234/NetworkComponents/5678.json

And to get that network component's uplink connection:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Hardware_Server/1234/NetworkComponents/5678/uplinkNetworkComponents.json

HTTP Request Types

DELETE

Use an HTTP DELETE request to delete an object instead of a service's deleteObject() method. For instance, pass an HTTP DELETE request to the following URL in order to remove domain record 1234 from AT&T Cloud Architect's DNS servers.

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Dns_Domain/1234.json

GET

Use HTTP GET requests for simple object retrieval and method calls. For instance, retrieve domain record id 1234 with an HTTP GET request to the URL:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Dns_Domain/1234.json

POST

Use an HTTP POST request to create an object instead of a service's createObject() or createObjects() methods. POST a single JSON or XML structure containing a single element called "parameters" containing your object's skeleton structure and any other parameters required by your API service's createObject() method. For instance, pass an HTTP POST request with the following data to the following URL in order to create a domain record in AT&T Cloud Architect's DNS servers.

{
    "parameters" : [
        {
            "name" : "example.org",
            "resourceRecords" : [
                {
                    "type" : "a",
                    "host" : "@",
                    "data" : "127.0.0.1"
                }
            ]
        }
    ]
}
https://username:apiKey@api.attcloudarchitect.com/rest/v3/Dns_Domain.json

PUT

Use an HTTP PUT request to edit an object instead of a service's editObject() or editObjects() methods. PUT a single JSON or XML structure containing a single element called "parameters" containing your object's skeleton structure and any other parameters required by your API service's editObject() method.

For instance, pass an HTTP PUT request with the following data to the following URL in order to edit domain resource record 5678 within domain record 1234 on AT&T Cloud Architect's DNS servers, changing its data to "10.0.0.1".

{
    "parameters" : [
        {
            "data" : "10.0.0.1",
        }
    ]
}
https://username:apiKey@api.attcloudarchitect.com/rest/v3/Dns_Domain/1234/ResourceRecords/5678.json

Passing Method Parameters

Parameters are passed in our REST API by appending each to the path of the URL.
These should be passed in the same order in which they are listed in the documentation for each method, from top to bottom.

For example Monitoring_Agent::setActiveAlarmSubscriber requires the userRecordId parameter:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Monitoring_Agent/1234/setActiveAlarmSubscriber/5678.json

Alternate Ways to Set Parameter and Return Formats

In addition to adding ".json" and ".xml" to your REST URL you can also set API call return formats by passing a MIME-type (application/json for JSON and text/xmlfor XML) in HTTP Accept or Content-Type headers in your request.

Using Object Masks

Create an object mask in your API call URL by adding an objectMask variable to your query string. Object masks are a semicolon-delineated list of relational properties, with chained relational properties separated by periods. In order to save space in the query string, REST object masks are relative to the data type at the end of your URL instead of the API service you're querying. Likewise, REST object masks don't contain a mask property.

The following URL creates an object mask that retrieves an account's hardware records along with the datacenters that hardware is located in. Note that the object mask only contains the relational property we want to retrieve related to hardware, not our account.

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/Hardware.json?objectMask=datacenter

This URL gets an account's hardware records along with that hardware's associated datacenter, operating system, and network component records. Note that these relational items are separate by semicolons.

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/Hardware.json?objectMask=datacenter;operatingSystem;networkComponents

This URL gets an account's hardware records along with that hardware's associated datacenter, operating system, operating system password, and network component records. Chained relational properties are separated by periods.

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/Hardware.json?objectMask=datacenter;operatingSystem.passwords;networkComponents

The REST API can handle object masks in a slightly different way than AT&T Cloud Architect's SOAP And XML-RPC APIs. REST object masks can be made to filter local data type properties retrieved from the AT&T Cloud Architect API. If you define a local property in your mask, then the AT&T Cloud Architect API treats your mask as a filter, and will only retrieve the local properties specified in your mask. For example, this URL retrieves only the ID and hostname properties in an account's hardware records:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/Hardware.json?objectMask=hardware.id;hardware.hostname

Using Result Limits

Limit the number of results in an API call by adding a resultLimit variable to your query string. Set your resultLimit variable to a comma-delineated set of two numbers:

  • The offset to begin your result set at
  • The number of results to limit your call to

This URL retrieves the first two tickets open on an account, calling the Account::getOpenTickets method:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Account/OpenTickets.json?resultLimit=0,2

Error Handling

The AT&T Cloud Architect REST API returns XML or JSON output with a single error node containing any error messages returned by your API call. For instance, the URL to the nonexistent service:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Nonexistent.xml

returns the error:

<root>
   <error>Service does not exist</error>
</root>

While its JSON equivalent:

https://username:apiKey@api.attcloudarchitect.com/rest/v3/Nonexistent.json

returns the error:

{
    "error": "Service does not exist"
}

Authentication Errors

The AT&T Cloud Architect REST API returns an HTTP 401 Unauthorized error if an invalid username / API key combination is used when requesting a REST URL.

Caveats

Specifying Complex Types

As with XML-RPC, the REST API cannot determine extended complex types in certain parameters. In these cases you should define a complexType property in your complex parameters set to the type of object you're sending to your method.

Referenced API Components

Services

Data Types

Methods