Request Formats

Request Formats
lac42
You can make requests using the JSON and XML request formats. JSON is the default request format. JSON arrays have container element XML counterpart. 
CA Live API Creator
 puts JSON object metadata attributes into XML elements as attributes. 
CA Live API Creator
 encodes XML tag names into a special XML valid format.
When making requests to 
CA Live API Creator
, specify the format of the payload using a 
Content-Type
 HTTP header.
For more information about this HTTP header, see HTTP Headers.
In this article:
 
 
Define the Expected Format
HTTP Methods: 
GET, POST, PUT, and DELETE
JSON
 
The following headers prescribes to API Server what format of response the client expects for JSON:
Header Name
Header Value
Content-Type
application/json
Accept
application/json
XML
 
The following headers prescribes to API Server what format of response the client expects for XML:
Header Name
Header Value
Content-Type
application/json
Accept
application/json
 Default Requests
(Table and resource endpoints) The following examples use the 
Demo
 sample API. GET requests that are made to an endpoint are the expected POST or PUT format when adding or updating records. You can determine what the structure would look like for your API using the REST Lab.
The simplest example for a client is making an authenticated GET request to the 
demo:customer
 endpoint. The following code snippet shows the JSON result:
[ { "name": "Alpha and Sons", "balance": 4484, "credit_limit": 9001, "@metadata": { "href": "http://my.acme.com/rest/default/demo_mysql/v1/demo:customer/Alpha%20and%20Sons", "checksum": "A:f54acaa0f3a5f0ee", "links": [ { "href": "http://my.acme.com/rest/default/demo_mysql/v1/demo:PurchaseOrder?sysfilter=equal(customer_name:'Alpha%20and%20Sons')", "rel": "children", "role": "PurchaseOrderList", "type": "urn:caliveapicreator:demo:demo:PurchaseOrder" }, { "href": "http://dev.expressologic.com/rest/default/demo_mysql/v1/finance:orders?sysfilter=equal(customer_name:'Alpha%20and%20Sons')", "rel": "children", "role": "financeOrders", "type": "urn:caliveapicreator:demo:finance:orders" } ] } } ]
The following code snippet shows the XML result:
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <list.demo.customer meta-next_batch="http://my.acme.com/rest/default/demo_mysql/v1/demo:customer?pagesize=20&#38;offset=20"> <demo.customer meta-checksum="A:6701f45750d76af5" meta-href="http://my.acme.com/rest/default/demo_mysql/v1/demo:customer/Alpha%20and%20Sons"> <name>Alpha and Sons</name> <balance>0</balance> <credit_limit>9000</credit_limit> </demo.customer> </list.customer> </root>
By default, JSON arrays are contained in an XML element prefixed with "
list.
" The XML elements nested in 
list
 elements, which represent JSON objects, include metadata as attributes prefixed with "
meta-
". When making a PUT request to update the 
credit_limit
 of the Alpha And Son's record, a client request body must include the same metadata attributes as in JSON, namely an 
href
 and 
checksum
.
Examples:
 
The following examples are for an XML PUT request and response:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <root> <list.customer meta-next_batch="http://my.acme.com/rest/default/demo_mysql/v1/demo:customer?pagesize=1&#38;offset=1"> <demo.customer meta-checksum="A:0acf613ae8af9bcb" meta-href="http://localhost:8080/APIServer/rest/default/demo_mysql/v1/demo:customer/Alpha%20and%20Sons"> <name>Alpha and Sons</name> <credit_limit>9001</credit_limit> </demo.customer> </list.customer> </root>
<?xml version="1.0" encoding="UTF-8"?> <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <result> <statusCode>200</statusCode> <list.txsummary> <demo.customer meta-href="http://my.acme.com/rest/default/demo/v1/demo:customer/Alpha%20and%20Sons" meta-verb="UPDATE" meta-checksum="A:f54acaa0f3a5f0ee"> <name>Alpha and Sons</name> <balance>4484</balance> <credit_limit>9001</credit_limit> </demo.customer> </list.txsummary> </result> </root>
XML Element Name Conventions & Conversions
 
CA Live API Creator
 must be able to encode and decode the full range of allowed characters for database columns and tables, as well as any aliases that the client might have defined for a resource defined in API Creator explicitly. XML does not allow many of the characters that are valid in a database schema. 
CA Live API Creator
 converts the characters into XML-valid and (hopefully) human readable character sets.
 
CA Live API Creator
 accepts only case-insensitive letters or other standard alpha characters. The conversion encodes all other characters into their Unicode-string equivalent, prefixed by a dash (-) and suffixed with a period (.), unless it is the first character in the tag. XML does not allow element names to begin with a dash. The conversion encodes the prefix with an underscore (_).
Metadata Requests
(Endpoints beginning in 
@
, such as 
/@tables
) Metadata endpoints allow for content types of XML. By default, most metadata requests make sense only as GET requests. But a request to the 
@authentication
 RESTful endpoint is a case for a POST HTTP method.
Example:
 
The following example shows a client request with JSON:
{
"username": "demo",
"password": "Password1"
}
<root> <authentication> <username>demo</username> <password>Password1</password> </authentication > </root>
Elements that are nested in the 
<result></result>
 tags are equivalent to a simple JSON object when querying metadata endpoints. Responses have nested lists and encoded tag names consistent with other resources.
For more information about how to modify the root element tag name, see API Properties.