Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation and initial release

  • Loading branch information...
commit 2e4d6fc6238e0c22f802751ccbf854e7264ec6d6 1 parent 5b268bf
@maxpert authored
Showing with 147 additions and 45 deletions.
  1. +143 −0 README.md
  2. +2 −1  lib/Reston.js
  3. +2 −44 test.js
View
143 README.md
@@ -0,0 +1,143 @@
+Reston 0.1.0
+===========
+
+MIT Licensed, (C) Zohaib Sibt-e-Hassan 2011
+
+A Rest client library to make rest interaction easy:
+
+Features
+--------
+
+* POST, GET, PUT, DELETE using native JSON objects for data
+* Easy to use
+* setRequestHeader like XHR object for directly manipulating headers = More power
+* Support for multipart request
+* Support for file upload
+* Simple utility wrappers
+* Totally event based (more flexible)
+
+API
+---
+
+### Reston.get(url)
+
+Basic method to make a get request object, example:
+
+ var req = Reston.get('http://foo.com/');
+ req.on('data', function(chunk){
+ console.log(chunk.toString());
+ });
+
+ req.send(); //Sends a simple get Request
+
+*URL must be properly formated i.e. must start with http:// (Currently only supports http, https coming soon)*
+
+### Reston.post(url)
+
+Creates a basic post request, e.g. Reston.post('http://place-to-post.com/save/');
+*URL must be properly formated i.e. must start with http:// (Currently only supports http, https coming soon)*
+
+### Reston.put(url)
+
+Creates a basic put request, e.g. Reston.put('http://place-to-put.com/update/');
+*URL must be properly formated i.e. must start with http:// (Currently only supports http, https coming soon)*
+
+### Reston.del(url)
+
+Creates a basic delete request, e.g. Reston.del('http://localhost/bye-bye/');
+*URL must be properly formated i.e. must start with http:// (Currently only supports http, https coming soon)*
+
+### new Reston.file(path_to_file, options)
+
+*path_to_file* is absolute path to file.
+*options* JSON object with following properties
+ mode(default 666),
+ buffer_length( default is same as file's blksize assigned aka OS block size on disk),
+ read_mode ('binary' by default and recommended)
+
+the created object in turn as data can be passed to sendMultiPart method of created request object to stream it as upload, example:
+
+ var req = Reston.post('http://localhost/upload.php');
+ req.on('success', function(){
+ console.log('done');
+ });
+ req.on('error', function(){
+ console.log('boooo!');
+ });
+ var data = {};
+ data.my_file_name = new Reston.file('/home/myname/file.zip');
+ data.some_other_field = 'Data';
+ data.more_data = 'text data here';
+ req.sendMultiPart(data);
+
+### setRequestHeader(name, value)
+
+Sets header to be sent in the request; does what's written on box!
+* Word of caution * Just dont try to mess around with headers like Host, Content-Length because it will propogate the set headers without any filters; so remember the rule; with great power comes great responsibility!
+
+
+### send(data)
+
+Send a simple get/post/put/del request automatically determining the query string to be sent incase of post/put or get/delete. The query string variables in URL creation would be. *data* must be JSON object with properties corresponding to values that will be serialized by querystring.stringify and merged with query string parameters in url (when object was created)
+
+*Warning* File upload wont work and may cause the send to mis-behave so use sentMultiPart in case your data contains Reston.file object
+
+### sendMultiPart(data)
+
+Make a multipart submission of POST/PUT request only; data specs remain the same as _send_ but adds acceptance for Reston.file object for file streaming.
+
+### Examples:
+
+POST request with file:
+ var req = Reston.post('http://localhost/upload.php');
+ req.on('success', function(){
+ console.log('done');
+ });
+ req.on('error', function(){
+ console.log('boooo!');
+ });
+ var data = {};
+ data.my_file_name = new Reston.file('/home/myname/file.zip');
+ data.some_other_field = 'Data';
+ data.more_data = 'text data here';
+ req.sendMultiPart(data);
+
+POST request without multipart:
+ var req = Reston.post('http://localhost/upload.php');
+ req.on('success', function(){
+ console.log('done');
+ });
+ req.on('error', function(){
+ console.log('boooo!');
+ });
+ var data = {};
+ data.foo = 'Data';
+ data.bar = 'text data here';
+ req.send(data);
+
+GET request with querystring+data as well:
+
+ var req = Reston.get('http://localhost/data.php?a=1&b=2&c=3');
+ req.on('success', function(){
+ console.log('done');
+ });
+ req.on('error', function(){
+ console.log('boooo!');
+ });
+ var data = {};
+ data.b = 5;
+ req.send(data); // Sends a=1, b=5, c=3 (look how it overrides the data for b)
+
+
+DEL request with querystring+data as well:
+
+ var req = Reston.del('http://localhost/data.php?a=1&b=2&c=3');
+ req.on('success', function(){
+ console.log('done');
+ });
+ req.on('error', function(){
+ console.log('boooo!');
+ });
+ var data = {};
+ data.b = 5;
+ req.send(data); // Makes a delete request Sends a=1, b=5, c=3 (look how it overrides the data for b)
View
3  lib/Reston.js
@@ -149,7 +149,8 @@ core.mixin(Reston, {
post: function(url){ return new Reston('POST', url); },
get: function(url){ return new Reston('GET', url); },
put: function(url){ return new Reston('PUT', url); },
- del: function(url){ return new Reston('DELETE', url); }
+ del: function(url){ return new Reston('DELETE', url); },
+ file: FileStream
});
if(module)
View
46 test.js
@@ -22,50 +22,8 @@ var request_object = function(method, address, headers){
var data = 'a=hello&b=world';
-var req = Reston.post('http://localhost/test1.php');
+var req = Reston.get('http://www.google.co.uk/');
req.on('data', function(c){
console.log(c.toString());
});
-req.sendMultiPart({
- 'file': new FileStream('/home/mxp/Downloads/1430225297ASPn.rar'),
- 'data': 'more data here'
-});
-
-/*
-var req = request_object('PUT', 'http://localhost/test1.php', {
- 'Content-Type': 'application/x-www-form-urlencoded',
- 'Content-Length': data.length});
-
-req.on('response', function(resp){
- console.log(resp.statusCode);
- resp.on('data', function(chunk){
- console.log(chunk.toString());
- });
-});
-req.write(data);
-req.end();
-
-var fl = new FileStream('/home/mxp/Downloads/1430225297ASPn.rar'),
- mw = new MultipartWriter({'filename': fl, 'name': 'zohaib'});
-
-
-var req = request_object('POST', 'http://localhost/test1.php', mw.headers());
-
-req.on('response', function(resp){
- console.log(resp.statusCode);
- resp.on('data', function(chunk){
- console.log(chunk.toString());
- });
-});
-
-mw.writebody(req);
-mw.on('complete', function(){
- req.end();
-});
-
-fl.on('error', function(err){
- console.log("Error...");
- console.log(err);
-});
-*/
-
+req.send();
Please sign in to comment.
Something went wrong with that request. Please try again.