Invoking APIs‎ > ‎

Request Formats

You can make requests using the following types of request formats:

  • JSON (default). JSON arrays have container element XML counterpart. JSON object metadata attributes are put into XML elements as attributes.
  • XML. XML tag names are encoded into a special XML valid format.

When making requests to API Creator, specify a Content-Type of the desired format.

Define the Expected Format

HTTP Methods: GET, POST, PUT, and DELETE

Headers

The following headers prescribes to API Server what format of response the client expects for JSON:

Header NameHeader Value
 Content-Type application/json
 Accept application/json

The following headers prescribes to API Server what format of response the client expects for XML:

Header NameHeader Value
Content-Typeapplication/xml
Acceptapplication/xml

Default Requests

(Tables & Resources Endpoints)

The following examples use the default Demo API project, though they are applicable to all API Creator APIs. Any GET request made to an endpoint is 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:

JSON

[
  {
    "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:

XML

<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&amp;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.

The following examples are for an XML PUT request and response:

XML PUT Request

<?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&amp;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 PUT Response

<?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

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 may have defined for a custom resource. XML does not allow many of the characters that are valid in a database schema. API Creator converts the characters into XML-valid and (hopefully) human readable character sets.

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 there is one obvious case for a POST method: an @authentication query. Clients requests with JSON are sparse by comparison:

@authentication JSON

{ "username": "demo", "password": "Password1" }

@authentication XML

<root>
  <authentication>
  <username>demo</username>
  <password>Password1</password>
  </authentication >
</root>

Elements nested in the <result></result> tags are equivalent to a simple JSON object when querying metadata endpoints. API Creator's unique behavior for a metadata endpoint should end there. Otherwise, responses will have nested lists and encoded tag names consistent with other resources.

More Information

For more information about modifying the Root Element tag name, see API Properties.