IO thoughts

Introduction

This WIKI entry describes desired capabilities of a IO library to be used with #space. It is kept high-level on purpose as not to prescribe any particular implementation. Thanks to this approach we can evaluate existing libraries or write our own if none of the existing ones fit the bill.

General considerations

The "ideal" library should be:

• Easy to use, modern API - this is subjective to a certain degree but at least typical cases should be obvious to write and shouldn't require excessive amounts of code.
• Feature rich - contain features needed to develop typical SPAs.
• Secure and security-friendly - the library itself should have built-in mechanism sanitizing typical vectors of attack as well as provide facilities to help developers write secure code for their applications
• Testable - that is, code written with the use of such library should be easy to mock and unit-test
• Lightweight - small code size and no 3rd party dependencies (polyffils are acceptable)
• Stable and of good quality - code for a library should be proven to work across the range of supported browsers

Details

The subsequent sections go into more details of each criterion and describe ideal APIs.

Easy to use, modern API

Typical scenarios

Firstly, the proposed library should be (very) easy to use for a typical use-cases. To discuss an ideal API let's consider 2 common use-cases:

• sending request without body-content (ex. GET, HEAD)
• sending request with body-content (ex. POST, PUT)

Request without body-content

The simplest GET call shouldn't require more than one line of code, ex.: io.get('http://site.com/folder'). The returned value should be a promise that:

• resolves to an object representing a response (having fields like response status, header and the response content)
• is rejected with an error if an issued request fails.

Full example:

io.get('http://site.com/folder').then(function(response){
  console.log(response.content);
});

Request with body-content

A simple POST request should be a one-liner, too. Ex.:

io.post('http://site.com/folder', {foo: 'bar'}).then(function(response){
  console.log(response.content);
});

Please notice that the proposed library is "smart enough" to properly convert a JavaScript object ({foo: 'bar'}) into a string. The most typical case is to convert a string to JSON but this should be configurable. The point here is that a user of a library shouldn't need to do low-level data-conversion and headers setting for typical scenarios, while still being free to fully control ongoing request when needed.

The incoming JSON response should be also automatically converted to a corresponding JavaScript object (depending on the response headers). Of course this mechanism should be configurable.

Request params serialization

As with body content, the library should be able to serialize request parameters, expressed as JavaScript objects, to their URL representation. For example, give this invocation:

io.get('http://site.com/folder', {params: {foo: 1, bar: false, baz: 'some string'}).then(function(response){
  console.log(response.content);
});

we should issue a request targeting the following URL (notice all the boilerplate string gluing and params encoding):

http://site.com/folder?foo=1&bar=false&baz=some%20string

Feature rich

There are many features that could be considered for a IO library. As an example jQuery's $.ajax API has over 30 (!) different toggles in their settings section... Obviously the goal here is not to add every possible feature that the most popular libraries got but rather to make sure that we support features that are useful for typical web applications. In my books the list of the features to support would be:

• configurable data conversion (both incoming and ongoing)
• request parameters serializers
• promise-based "around" interceptors - this IMO is the must as the number of use-cases that can be covered with interceptors without any need for the build in-library functionality. I wouldn't be surprised if 1/2 of all the jQuery settings could be covered by a dedicated interceptors (caching is a good example here).

Secure and security-friendly

Open questions

There are several items where I'm not clear on the recommendation(s) or even if a give feature should be supported at all:

• CORS support - IE<10 is known to have half-broken CORS support. There are various work-arounds but those might substantially increase library's size.
• file:// protocol support
• synchronous requests support
• client-side cache - I would probably see it as a separate module where a cache could be plugged with a dedicated interceptor
• JSONP support?