Requests

Shortcuts:

HTTP Request Overview

Browsers or other HTTP application client programs send an HTTP request with a URL, parameters, headers and, optionally, data to a server. Requests are English-oriented and consist of text lines terminated by carriage return (ASCII value 13) and line feed (ASCII value 10) characters (CRLF). HTTP request messages consist of:

A complete HTTP request might look like the following. This request does not require a request body

GET http://ebillinghub.com/ HTTP/1.1
Host: ebillinghub.com
Proxy-Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1700.41 Safari/537.36
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8

HTTP Requests for the EBH Data Service

When a browser or client application program sends an HTTP request messages to the EBH Data Service, the request must consist of:

The complete HTTP request for this example would be:

GET https://dataservice.ebillinghub.com/api/v1/invoices/1234 HTTP/1.1
Authorization: Basic dXNlcmlkOnBhc3N3b3Jk
Accept: application/xml

Specifying URL Parameters

Many of the queries provided by the EBH Data Service require parameters, such as searches using an invoice number, a matter ID, or the beginning and ending dates of an invoice date range. These parameters can be specified either via RESTful syntax as part of the URL "path" (for example, invoices/1234) or as a query string parameter (for example, invoices?invoice=1234).

RESTful Syntax for Parameters

When including parameters as part of the URL path, the general syntax of the URL is "GET", space, base path to the EBH data service, slash, "api", slash, API version, slash, object type, slash, query type, slash, parameter value, slash, parameter value, space, protocol version. Note that the status search for invoices has a slightly different syntax since that search can be either for a single invoice status or a list of possible statuses in a CSV list. The initial request line for some query requests might be:

Specifying Parameters via Query String Parameters

When including parameters as query string parameters, the general syntax of the URL is "GET", space, base path, slash, "api", slash, API version, slash, object type, question mark, parameter name, equals sign, parameter value, ampersand, parameter name, equals sign, parameter value, space, protocol version. Specifying the parameters via query string parameters for the above initial request lines would look like this:

Specifying Parameters for the Search API

Queries provided by the EBH Data Service only support a single search criterion (for example, searching for invoices for a particular matter ID). The Search API must be used for searches involving multiple criteria (for example, searching for invoices for a particular matter ID and that also have a current invoice status of "ebilled"). The general syntax of the URL is "GET", space, base path, slash, "api", slash, API version, slash, "search", slash, object type, question mark, parameter name, equals sign, parameter value, ampersand, parameter name, equals sign, parameter value, space, protocol version. Some sample initial request lines for the Search API might look like this:

Details about all of the query types provided by the EBH Data Service along with the parameters for the queries is available at the "API interfaces available" help pages.

Security for a Request

Two important details are needed for securing requests sent to the EBH Data Service:

  1. The request must be sent via HTTPS to safeguard the credentials while the request travels via the Internet.
  2. The request must include an Authorization header for basic authentication. This header includes a base-64 encoding of the firm's userid and password for using the EBH Data Service. The encoded string must be in the format of userid colon password, then base-64 encoded.

If a request does not contain an Authorization header, the EBH Data Service will respond to the request with a 401 Unauthorized HTTP status code. When using a browser as the client program for issuing a request by entering the full URL in the address bar, the browser automatically recognizes the 401 Unauthorized code, issues a prompt for the user to enter appropriate credentials and then reissues the request with the Authorization header included in the request. This second request will successfully return data if the credentials are correct. Otherwise, another 401 Unauthorized response will be issued and the second request will fail.

When using an application program other than a browser to issue requests to the EBH Data Service, the program must include the Authorization header in the request or be able to respond appropriately to the 401 Unauthorized challenge for credentials.

Note that access to the EBH Data Service requires a separate license, so contact your account manager for information about licensing this option.

A tool for creating an Authorization header is available here.

Negotiating the Returned Data Content Type

The EBH Data Service can return data formatted as XML or JSON text. The browser or client application program negotiates the content type of the returned data by including an Accept header in the request or by including an Output parameter in the query string parameters for the URL.

Content Negotiation Via Headers

Include one of the following headers in the request:

A complete request using this method might look like the following:

GET https://dataservice.ebillinghub.com/api/v1/invoices/1234 HTTP/1.1
Authorization: Basic dXNlcmlkOnBhc3N3b3Jk
Accept: application/xml
Content Negotiation Via Query String Parameters

Include one of the following parameters as a query string paramater for the URL:

A complete request using this method might look like the following:

GET https://dataservice.ebillinghub.com/api/v1/invoices/1234?output=xml HTTP/1.1
Authorization: Basic dXNlcmlkOnBhc3N3b3Jk
Default Content Negotiation

If a request does not include an Accept header, then the reponse will include JSON data. When using a browser as the client program for issuing a request by entering the full URL in the address bar, the browser includes its default Accept headers in the request. These defaults vary depending on the browser. For example, Chrome sends requests with an Accept header that includes "application/xml" as one of the supported content types.

On the other hand, Internet Explorer sends requests with an Accept header that does not include any XML options, so the response includes JSON data. However, IE has limited support for JSON text and will issue an error message. Always include the output=xml query string parameter when using IE to send requests to the EBH Data Service.

As a recommended "best practice", all requests to the EBH Data Service should always use the Accept header or output query string parameter to negotiate the response data's content type to ensure that the data will be be formatted the way that the application program expects.

Paging through a Multi-Page Resultset

Some requests to the EBH Data Service may return a large volume of data. In this case, the Data Service returns a response with a small page of the resultset. The application program must issue additional requests to retrieve subsequent pages of the resultset.

All data types returned by the EBH Data Service contain properties that indicate whether the response includes the entire resultset or just a page within the resultset.

The application program must check the queryTotalRows and rowNumber properties on the last row of a response to determine whether the entire resultset has been returned. If the values match, then all of the rows have been returned. If they differ, then the application program must issue another request to obtain the next page of data. The subsequent requests must contain query string parameters to indicate which page of data should be returned in the response.

The following example shows how to page through a multi-page resultset. Note that some of the headers in the requests and most of the properties in the data return in the response have been omitted from this example for brevity.

  1. Request: GET https://dataservice.ebillinghub.com/api/v1/invoices HTTP/1.1
    Response last data row: rowNumber=500, queryTotalRows=1037
  2. Request: GET https://dataservice.ebillinghub.com/api/v1/invoices&skip=500 HTTP/1.1
    Response last data row: rowNumber=1000, queryTotalRows=1037
  3. Request: GET https://dataservice.ebillinghub.com/api/v1/invoices&skip=1000 HTTP/1.1
    Response last data row: rowNumber=1037, queryTotalRows=1037