Response format

HTTP headers

A response code giving an initial indication of success or failure of an API call will be provided in the headers. For example, attempting to retrieve fax status information with incorrect InterFAX credentials will return an HTTP status code of 401 UNAUTHORIZED.

Upon successful creation of a new resource with a POST method, an HTTP “Location:” header will provide the URI of the newly-created resource. For example, when sending a fax with the POST /outbound/faxes operation, a successful response will return the location where the status of the fax can be queried, like
Location: https://rest-sl.interfax.net/outbound/faxes/131201409296898.

HTTP content

Response content may occasionally be empty, with the required information being relayed by the HTTP response code (200, 404, etc.) and, optionally, the “Location:” header.

When the content area isn’t empty, its format will vary depending on the requested response format – JSON (Default), XML, or HTML. It will generally be structured as to show:

Upon success

1. Operation-dependent content, e.g. fax meta data
2. Optional MIME content, e.g. the TIFF image of a fax

Upon error

A structure providing the InterFAX response code, for example:

{
    "code":-113,
    "message":"Do we need this",
    "more_info":"List name [MyList2] does not exist"
}

A helper method that shows all possible REST response codes status is available at https://rest-sl.interfax.net/tests/errorcodes.

HTTP content formats

JSON (Default)

By default, REST requests will receive a JSON-structured response. For example, a response from operation GET /outbound/faxes/{id} will return the following:

{
    "id"     : 987654321,
    "basic"  :
    {
       "parentID"     : 876543210,
       "status"       : -3,
       "duration"     : 55
    }
}

Not defining a response type in the URL is equivalent to setting the “Accept:” header to “application/json”.

XML

To force the API to return a response as XML, set the “Accept:” header to “text/xml”. An XML response will be structured as:

       876543210
       -3
       55

MIME content

TBD

Custom Headers

X-Elapsed-Time shows the time in milliseconds that it took to process the returned API call.