Skip to content

Commit

Permalink
rest.js is now part of Cujo.js
Browse files Browse the repository at this point in the history
  • Loading branch information
@scothis
scothis committed Mar 22, 2013
1 parent bd150ab commit a3c42bd
Show file tree
Hide file tree
Showing 80 changed files with 446 additions and 1,543 deletions.
4 changes: 2 additions & 2 deletions .travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ script: npm run-script ci
env:
global:
- BUSTER_TEST_OPT="--reporter specification"
- SELENIUM_USERNAME=s2js-rest
- secure: "jMkfzJLwEdNVNkFDdc/slTTopqJR4uoUsGElmrChrzj3wr9x8Yy2Cu1gYcLx\navO9g6Rw4DzN8uVwFLufr8aTbfMtdN7fUZWC3SdCXpTu15b6hm6Zp7wvqhWp\nlPT6QSZbKtw7h5++ffh2SvLln2JPwghbxrEI31quIXQhefDA/0Y="
- SELENIUM_USERNAME=cujojs-rest
- secure: "kxs2tHuJ3Vd1lO/mBoUJ5EpLdojYuAsCGm7xP03VVjuuJs7zf1gux3xx3e+5\nb2LaZL4p4/rPmkPaYGNmh/FE2XrmcAejF1bSKyX0VLD0LUPnB/afwWMF1vvI\nupa+JAXxNlM2tNaK+TiLdq0uFhjs8GyTdxHm9jujdzOmGf7IF8o="
99 changes: 20 additions & 79 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
_Have something you'd like to contribute to the framework? We welcome pull
requests, but ask that you carefully read this document first to understand how
best to submit them; what kind of changes are likely to be accepted; and what
to expect from the Spring team when evaluating your submission._
_Thanks for your interest in rest.js. Have something you'd like to contribute?
We welcome pull requests, but ask that you read this document first to
understand how best to submit them; what kind of changes are likely to be
accepted; and what to expect from the team when evaluating your submission._

_Please refer back to this document as a checklist before issuing any pull
request; this will save time for everyone!_
Expand All @@ -24,29 +24,10 @@ truly trivial, e.g. typo fixes, removing compiler warnings, etc.
## Discuss non-trivial contribution ideas with committers

If you're considering anything more than correcting a typo or fixing a minor
bug, please discuss it on the [s2js-contrib][] mailing list before submitting a
pull request. We're happy to provide guidance but please research the subject
on your own including searching the mailing list for prior discussions.


## Sign the Contributor License Agreement

If you have not previously done so, please fill out and submit the
[s2js CLA form][]. You'll receive a token when this process is complete. Keep
track of this; you may be asked for it later!

Note that emailing/postal mailing a signed copy is _not_ necessary. Submission
of the web form is all that is required.

Once you've completed the web form, simply add the following in a comment on
your pull request:

I have signed and agree to the terms of the s2js Contributor License
Agreement.

You do not need to include your token/id. Please add the statement above to all
future pull requests as well, simply so that the team knows immediately that
this process is complete.
bug, please discuss it on the cujojs [mailing list][], or the #cujojs IRC
channel on freenode, before submitting a pull request. We're happy to provide
guidance but please research the subject on your own including searching the
mailing list for prior discussions.


## Create your branch from `dev`
Expand Down Expand Up @@ -84,49 +65,37 @@ present in the framework.
1. Preserve existing formatting; i.e. do not reformat code for its own sake
1. Search the codebase using `git grep` and other tools to discover common
naming conventions, etc.
1. ascii encoding for JS sources, escape special characters
1. utf8 encoding for JS sources, escape special characters


## Add MIT license header to all new source files
## Add MIT license block to all new source files

```javascript
/*
* Copyright (c) 2013 VMware, Inc. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
* sell copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
* Copyright 2013 the original author or authors
* @license MIT, see LICENSE.txt for details
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
* IN THE SOFTWARE.
* @author FirstName LastName <OptionalEmailAddress>
*/
```

If you are uncomfortable making the contribution under the MIT license, please
contact us before making a contribution.


## Update license header to modified files as necessary

Always check the date range in the license header. For example, if you've
modified a file in 2013 whose header still reads

```javascript
* Copyright (c) 2012 VMware, Inc.
* Copyright 2012 the original author or authors
```

then be sure to update it to 2013 appropriately

```javascript
* Copyright (c) 2012-2013 VMware, Inc.
* Copyright 2012-2013 the original author or authors
```


Expand Down Expand Up @@ -159,33 +128,6 @@ there are many resources online to help you understand how these tools work.
Here is one: http://book.git-scm.com/4_interactive_rebasing.html.


## Use real name in git commits

Please configure git to use your real first and last name for any commits you
intend to submit as pull requests. For example, this is not acceptable:

Author: Nickname <[email protected]>

Rather, please include your first and last name, properly capitalized, as
submitted against the SpringSource contributor license agreement:

Author: First Last <[email protected]>

This helps ensure traceability against the CLA, and also goes a long way to
ensuring useful output from tools like `git shortlog` and others.

You can configure this globally via the account admin area GitHub (useful for
fork-and-edit cases); globally with

git config --global user.name "First Last"
git config --global user.email [email protected]

or for the local repository only by omitting the '--global' flag:

git config user.name "First Last"
git config user.email [email protected]


## Format commit messages

Please read and follow the [commit guidelines section of Pro Git][].
Expand Down Expand Up @@ -283,8 +225,7 @@ issue a new pull request when asked to make changes.


[help documentation]: http://help.github.com/send-pull-requests
[issue tracker]: https://github.com/s2js/rest/issues
[s2js-contrib]: https://groups.google.com/forum/#!forum/s2js-contrib
[s2js CLA form]: http://support.springsource.com/spring_s2js_signup
[issue tracker]: https://github.com/cujojs/rest/issues
[mailing list]: https://groups.google.com/forum/#!forum/cujojs
[fork-and-edit]: https://github.com/blog/844-forking-with-the-edit-button
[commit guidelines section of Pro Git]: http://progit.org/book/ch5-2.html#commit_guidelines
11 changes: 10 additions & 1 deletion LICENSE.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Copyright (c) 2012-2013 VMware, Inc. All Rights Reserved.
Copyright (c) 2012-2013 the original author or authors

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
Expand All @@ -17,3 +17,12 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


---

Code published by Scott Andrews or Jeremy Grelle is copyright VMware.

VMware, Inc.
3401 Hillview Avenue
Palo Alto, CA 94304
45 changes: 21 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
Rest.js
rest.js
=======

Just enough client, as you need it. Make HTTP requests from a browser or Node.js applying the only the client features you need. Configure a client once, and share it safely throughout your application. Easily extend with interceptors that wrap the request and/or response, or MIME type converters for rich data formats.
Just enough client, as you need it. Make HTTP requests from a browser or Node.js applying only the client features you need. Configure a client once, and share it safely throughout your application. Easily extend with interceptors that wrap the request and/or response, or MIME type converters for rich data formats.


Build Status
------------

<table>
<tr><td>Master</td><td><a href="http://travis-ci.org/s2js/rest" target="_blank"><img src="https://secure.travis-ci.org/s2js/rest.png?branch=master" /></a></tr>
<tr><td>Development</td><td><a href="http://travis-ci.org/s2js/rest" target="_blank"><img src="https://secure.travis-ci.org/s2js/rest.png?branch=dev" /></a></tr>
<tr><td>Master</td><td><a href="http://travis-ci.org/cujojs/rest" target="_blank"><img src="https://secure.travis-ci.org/cujojs/rest.png?branch=master" /></a></tr>
<tr><td>Development</td><td><a href="http://travis-ci.org/cujojs/rest" target="_blank"><img src="https://secure.travis-ci.org/cujojs/rest.png?branch=dev" /></a></tr>
</table>


Usage
-----

Using Rest.js is easy. The core clients provide limited functionality around the request and response lifecycle. The input and response objects are normalized to support portability between browser and server environments.
Using rest.js is easy. The core clients provide limited functionality around the request and response lifecycle. The request and response objects are normalized to support portability between different JavaScript environments.

The response from a client is a promise that is resolved when the remote request finishes.
The return value from a client is a promise that is resolved with the response when the remote request finishes.

The core client behavior can be augmented with interceptors. An interceptor wraps the client and transforms the request and response. For example: an interceptor may authenticate a request, or reject the promise if an error is encountered. Interceptors may be combined to create a client with the desired behavior. A configured interceptor acts just like a client. The default client is dumb, it only know the low level mechanics of making a request and parsing the response. All other behavior is applied and configurated with interceptors.
The core client behavior can be augmented with [interceptors](docs/interceptors.md#interceptor-principals). An interceptor wraps the client and transforms the request and response. For example: an interceptor may authenticate a request, or reject the promise if an error is encountered. Interceptors may be combined to create a client with the desired behavior. A configured interceptor acts just like a client. The core clients are basic, they only know the low level mechanics of making a request and parsing the response. All other behavior is applied and configurated with interceptors.

Interceptors are applied to a client by chaining. To chain a client with an interceptor to a client, call the `chain` function on the client providing the interceptor behavior and optionally a configuration object. A new client is returned containing the new behavior applied to the client. It's important to note that the behavior of the original client is not modified, in order to use the new behavior, you must use the returned client.
Interceptors are applied to a client by chaining. To chain a client with an interceptor, call the `chain` function on the client providing the interceptor and optionally a configuration object. A new client is returned containing the interceptor's behavior applied to the parent client. It's important to note that the behavior of the original client is not modified, in order to use the new behavior, you must use the returned client.


### Making a basic request: ###
Expand All @@ -42,7 +42,7 @@ The response should look familiar as well, it contains all the fields you would

### Working with JSON: ###

If you paid attention when executing the previous example, you may have noticed that the response.entity is a string. Often we work with more complex data types. For this, Rest.js supports a rich set of MIME type conversions with the `mime` interceptor. The correct converter will automatically be chosen based on the `Content-Type` response header. Custom converts can be registered for a MIME type, more on that later...
If you paid attention when executing the previous example, you may have noticed that the response.entity is a string. Often we work with more complex data types. For this, rest.js supports a rich set of [MIME type conversions](docs/mime.md) with the [MIME Interceptor](docs/interceptors.md#module-rest/interceptor/mime). The correct converter will automatically be chosen based on the `Content-Type` response header. Custom converts can be registered for a MIME type, more on that later...

```javascript
var rest, mime, client;
Expand Down Expand Up @@ -80,16 +80,16 @@ client({ path: '/data.json' }).then(
);
```

In this example, we take the client create by the `mime` interceptor, and wrap it with the `errorCode` interceptor. The errorCode interceptor accepts a configuration object that indicates what status codes should be considered an error. In this case we override the default value of <=400, to only reject with 500 or greater status code.
In this example, we take the client create by the [MIME Interceptor](docs/interceptors.md#module-rest/interceptor/mime), and wrap it with the [Error Code Interceptor](https://github.com/s2js/rest/blob/cujojs/docs/interceptors.md#module-rest/interceptor/errorCode). The error code interceptor accepts a configuration object that indicates what status codes should be considered an error. In this case we override the default value of <=400, to only reject with 500 or greater status code.

Since the errorCode interceptor can reject the response promise, we also add a second handler function to receive the response for requests in error.
Since the error code interceptor can reject the response promise, we also add a second handler function to receive the response for requests in error.

Clients can continue to be composed with interceptors as needed. At any point the client as configured can be shared. It is safe to share clients and allow other parts of your application to continue to compose other clients around the shared core. Your client is protected from additional interceptors that other parts of the application may add.


### Declarative Interceptor Composition: ###

First class support is provided for declaratively composing interceptors using [wire.js](https://github.com/cujojs/wire). Wire is an dependency injection container; you specify how the parts of your application interrelate and wire takes care of the dirty work to make it so.
First class support is provided for [declaratively composing interceptors using wire.js](docs/wire.md). wire.js is an dependency injection container; you specify how the parts of your application interrelate and wire takes care of the dirty work to make it so.

Let's take the previous example and configure the client using a wire specification instead of imperative code.

Expand Down Expand Up @@ -129,7 +129,7 @@ registry.register('application/vnd.com.example', {
});
```

Registering a custom converter is a simple as calling the register function on the mime registry with the type and converter. A converter has just two methods: `read` and `write`. Read converts a String to a more complex Object. Write converts an Object back into a String to be sent to the server. HTTP is fundamentally a text based protocol after all.
Registering a custom converter is a simple as calling the register function on the [mime registry](docs/mime.md#module-rest/mime/registry) with the type and converter. A converter has just two methods: `read` and `write`. Read converts a String to a more complex Object. Write converts an Object back into a String to be sent to the server. HTTP is fundamentally a text based protocol after all.

Built in converters are available under `rest/mime/type/{type}`, as an example, JSON support is located at `rest/mime/type/application/json`. You never need to know this as a consumer, but it's a good place to find examples.

Expand All @@ -149,13 +149,13 @@ Tested environments:
- Safari (5, 6, iOS 4-6, should work in earlier versions)
- Opera (11, 12, should work in earlier versions)

Specific browser test are provided by [Travis CI](https://travis-ci.org/s2js/rest) and [Sauce Labs' Open Sauce Plan](https://saucelabs.com/opensource). You can see [specific browser test results](https://saucelabs.com/u/s2js-rest), although odds are they do not reference this specific release/branch/commit.
Specific browser test are provided by [Travis CI](https://travis-ci.org/cujojs/rest) and [Sauce Labs' Open Sauce Plan](https://saucelabs.com/opensource). You can see [specific browser test results](https://saucelabs.com/u/cujojs-rest), although odds are they do not reference this specific release/branch/commit.


Getting Started
---------------

Rest can be installed via [npm](https://npmjs.org/), [Bower](http://twitter.github.com/bower/), or from source.
rest.js can be installed via [npm](https://npmjs.org/), [Bower](http://twitter.github.com/bower/), or from source.

To install without source:

Expand All @@ -169,9 +169,9 @@ From source:

$ npm install

Rest.js is designed to run in a browser environment, utilizing [AMD modules](https://github.com/amdjs/amdjs-api/wiki/AMD), or within [Node.js](http://nodejs.org/). [curl](https://github.com/cujojs/curl) is highly recommended as an AMD loader, although any loader should work.
rest.js is designed to run in a browser environment, utilizing [AMD modules](https://github.com/amdjs/amdjs-api/wiki/AMD), or within [Node.js](http://nodejs.org/). [curl.js](https://github.com/cujojs/curl) is highly recommended as an AMD loader, although any loader should work.

An ECMAScript 5 compatible environment is assumed. Older browsers, ::cough:: IE, that do not support ES5 natively can be shimmed. Any shim should work, although we've tested against cujo's [poly](https://github.com/cujojs/poly)
An ECMAScript 5 compatible environment is assumed. Older browsers, ::cough:: IE, that do not support ES5 natively can be shimmed. Any shim should work, although we've tested against cujo's [poly.js](https://github.com/cujojs/poly)


Documentation
Expand All @@ -183,7 +183,7 @@ Full project documentation is available in the [docs directory](docs).
Reporting Issues
----------------

Please report issues on [GitHub](https://github.com/s2js/rest/issues). Include a brief description of the error, information about the runtime (including shims) and any error messages.
Please report issues on [GitHub](https://github.com/cujojs/rest/issues). Include a brief description of the error, information about the runtime (including shims) and any error messages.

Feature requests are also welcome.

Expand Down Expand Up @@ -219,19 +219,16 @@ Please see CONTRIBUTING.md for details on how to contribute to this project.
Copyright
---------

Rest.js is made available under the MIT license. See LICENSE.txt for details.
Copyright 2012-2013 the original author or authors

Copyright (c) 2012-2013 VMware, Inc. All Rights Reserved.

VMware, Inc.
3401 Hillview Avenue
Palo Alto, CA 94304
rest.js is made available under the MIT license. See LICENSE.txt for details.


Change Log
----------

.next
- moving from the 's2js' to the 'cujojs' organization
- Dropping Node 0.6 support
- Interceptor configuration chaining
- wire.js factory
Expand Down
Loading

0 comments on commit a3c42bd

Please sign in to comment.