EMI-RPC protocol is communicating with EMI Server over HTTP. EMI Server is listening for EMI-RPC requests on a specified port. By default, EMI Server is listening for port 2001. In this respect EMI Server implements a limited HTTP server functionality that is compliant to HTTP protocol version 1.1 specification.

HTTP POST Request Considerations

Requests sent to EMI Server can be encapsulated in HTTP POST requests. There are only two header fields that are required by EMI Server: “Content-Type: application/json” and “Content-Length”. Any other header field will be ignored by the daemon. Hence the typical request will look like this:

POST emid HTTP/1.1
Host: 192.168.0.1:2001
Content-Type: application/json; charset=UTF-8
Content-Length: <SIZE OF EMI-RPC REQUEST>

<EMI-RPC REQUEST>

HTTP POST Response Considerations

A typical response from EMI Server would look like this:

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Date: Fri, 31 Dec 1999 23:59:59 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: <SIZE OF EMI-RPC RESPONSE>
Pragma: no-cache
Cache-Control: no-cache
Connection: close

<EMI-RPC RESPONSE>

The header is constructed to comply with HTTP 1.1. It instructs the client software not to use persistent TCP connections and not to use cached information. On top of that EMI Server accepts and serves only UTF-8 encoded data. Hence, there is a need for the “charset” declaration in the header.

100 CONTINUE

The HTTP 1.1 specification defines the provisional response 100 to facilitate better usage over the slow links. For that reason, every client or server that is HTTP/1.1 compliant should implement the following protocol.

• Client may send only the header of the message and pause till it receives the “100 Continue” message to send the rest of the request.
• Server must send the provisional “100 Continue” message as soon as it receives the header successfully. Otherwise it must send an error.

HTTP GET Request Considerations

From the EMI Server point of view, the HTTP-POST request method is the sufficient and is the preferred way to serve the data, it is a subject to security restrictions when the EMI Client is implemented to run in a common browser utilizing JavaScript. Namely, browsers are enforcing the “same origin” policy when both data and representation have to be loaded from the same source.

To solve this problem EMI Server also implements a JSONP access mechanism. If EMI Server receives a GET request, daemon considers it a JSONP request and handles accordingly. The GET parameters must include the following:

• callback – Name of the function to wrapper
• request – EMI-RPC JSON object (same as in POST request)

Any other parameter is ignored by the EMI Server. Following is the sample GET request. (In the following example “EMI-RPC DATA” is a placeholder for the real request data):

GET emid?callback=jsonp_callback&request=<EMI-RPC DATA> HTTP/1.1
Host: 192.168.0.1:2001

EMI Server will produce the following output:

HTTP/1.1 200 OK
Date: Fri, 31 Dec 1999 23:59:59 GMT
Content-Type: application/javascript; charset=UTF-8
Content-Length: <SIZE OF RESPONSE DATA>
Pragma: no-cache
Cache-Control: no-cache
Connection: close

jsonp_callback(“<EMI-RPC RESPONSE>”);

Please refer to the “Accessing EMI Server with JSONP “ for more information on the client-side implementation.

JSONP uses HTTP GET requests only. Hence following applies:

• The request parameters have to be encoded into the proper URI.
• There will be no “100 Continue” message from the EMI Server.
• There could be a browser or proxy limit on how long the GET request may be. Some versions of the browser were limited to around 2-4k. It is the responsibility of the UI developer to make sure that such limits are considered.

HTTP 1.1 Compliance Considerations

While EMI Server is more or less compliant with the HTTP/1.1 specification, in this section we clarify the limitations of the implemented protocol. According to the specification, any compliant server should do at least the following:

• Require the HOST header from HTTP 1.1 clients. EMI Server does not implement this requirement.
• Accept absolute URL in a request. This feature is not relevant to EMI Server. It is serving a single resource, hence resource addressing is ignored.
• Accept requests with chunked data.
• Either support persistent connections, or include the “Connection: close” header with each response.
• Use the “100 Continue” response appropriately.
• Include the Date: header in each response.
• Handle requests with If-Modified-Since: or If-Unmodified-Since: headers. Not implemented because EMI Server never serves cached HTTP data.
• Support at least GET and HEAD methods. HEAD method is not used by EMI Server. In order to comply under this requirement EMI Server responds with a 404 error on such requests.
• Support HTTP 1.0 requests. EMI Server may generate large amounts of data in which case data chunking is required. HTTP 1.0 does not support this feature, hence EMI Server will respond with error 505 to any HTTP/1.0 request.

Chunked Transfer

It is possible that both request and/or response may contain relatively large amount of data that is not always possible to construct at once. The biggest implication of this is that Content-Length might be unknown at the time of header construction. To handle this problem HTTP/1.1 has a possibility of including a chain of smaller data chunks in the message. Instead of Content-Length header field the “Transfer-Encoding: chunked” is used. The chunked information is as follows:

Transfer-Encoding: chunked

<size of the first chunk> (;<extension> optional)
<first chunk>
<size of the second chunk> (;<extension> optional)
<second chunk>
0
<optional headers>

EMI Server ignores all the optional parameters and the information EMI Server will actually understand will look like this:

Transfer-Encoding: chunked

4
[{},
3
{}]
0

HTTP Related Error Reporting

This section lists all the error conditions and corresponding error messages that are considered in EMI Server implementation.

HTTP/1.0 505 HTTP Version Not Supported
Pragma: no-cache
Cache-Control: no-cache
Connection: close

HTTP/1.1 404 Not Found
Pragma: no-cache
Cache-Control: no-cache
Connection: close

HTTP/1.1 400 Bad Request
Pragma: no-cache
Cache-Control: no-cache
Connection: close

HTTP/1.1 415 Unsupported Media Type
Pragma: no-cache
Cache-Control: no-cache
Connection: close

HTTP/1.1 501 Not Implemented
Pragma: no-cache
Cache-Control: no-cache
Connection: close

HTTP/1.1 503 Service Unavailable
Pragma: no-cache
Cache-Control: no-cache
Connection: close