Restangular Deployment and Usage Guide

Prerequisites

Node.js (v4.0.0 or higher) - Required for building and testing
npm (v2.0.0 or higher) - Node.js package manager
Browsers - For testing (Chrome, Firefox, PhantomJS, etc.)
AngularJS 1.x - Restangular is designed for AngularJS applications

Installation

Adding Restangular to your AngularJS project

Option 1: Using npm

npm install restangular --save

Option 2: Using Bower

bower install restangular --save

Option 3: Manual download

Download the latest release from the GitHub releases page
Extract the files and include dist/restangular.js or dist/restangular.min.js in your project

Setting up the development environment

Clone the repository:

git clone https://github.com/mgonto/restangular.git
cd restangular

Install dependencies:

npm install

Configuration

Environment Variables

No specific environment variables are required for Restangular itself.

Configuration Options

Restangular provides extensive configuration options that can be set globally or per-service:

Global Configuration (in your AngularJS app config)

angular.module('myApp', ['restangular'])
  .config(function(RestangularProvider) {
    // Set base URL for all API requests
    RestangularProvider.setBaseUrl('https://api.example.com/v1');
    
    // Add default headers
    RestangularProvider.setDefaultHeaders({'Authorization': 'Bearer YOUR_TOKEN'});
    
    // Configure response interceptors
    RestangularProvider.setResponseInterceptor(function(data, operation) {
      // Handle wrapped responses
      return data.data;
    });
  });

Available Configuration Methods

setBaseUrl(url) - Sets the base URL for all API requests
setDefaultHeaders(headers) - Sets default headers for all requests
setResponseInterceptor(fn) - Configures how responses are processed
setRequestInterceptor(fn) - Configures how requests are processed
setFullRequestInterceptor(fn) - Intercepts the entire request configuration
setErrorInterceptor(fn) - Handles error responses
setRestangularFields(fields) - Customizes field names (id, route, etc.)
setMethodOverriders(overriders) - Customizes HTTP method overriders
setDefaultRequestParams(params) - Sets default request parameters
setFullResponse(boolean) - Controls whether full response objects are returned
setRequestSuffix(suffix) - Adds a suffix to all requests
setUseCannonicalId(boolean) - Controls ID field usage
setPlainByDefault(boolean) - Controls default plain object behavior

Build & Run

Building the project locally

Development build (with source maps):

grunt

Production build (minified):

grunt uglify

Testing:

# Run tests once
grunt karma:build

# Run tests in watch mode
grunt karma:debug

# Run tests with Underscore instead of Lodash
grunt karma:buildUnderscore

Running tests

# Single run
npm test

# Continuous testing
npm run test:watch

Development server

Restangular doesn't include a development server. You'll need to integrate it into your existing AngularJS application.

Deployment

For the Restangular library itself

Restangular is a JavaScript library meant to be included in your AngularJS application. Deployment involves:

Build the library:

grunt build

Include in your AngularJS app:

<!-- Development -->
<script src="path/to/restangular.js"></script>

<!-- Production -->
<script src="path/to/restangular.min.js"></script>

Add as a dependency:

angular.module('myApp', ['restangular']);

For applications using Restangular

Deploy your AngularJS application using your preferred method:

Static hosting (recommended for AngularJS apps)

GitHub Pages - Free hosting for static sites
Netlify - Modern static site hosting with continuous deployment
Vercel - Serverless deployment platform
AWS S3 + CloudFront - Scalable static hosting

Traditional hosting

Apache/Nginx - Serve static files
Heroku - Platform-as-a-service (with buildpack for static sites)

Troubleshooting

Common Issues and Solutions

1. "Restangular is not defined" error

Problem: Restangular module not properly injected Solution: Ensure you've added restangular as a dependency in your AngularJS module:

angular.module('myApp', ['restangular']);

2. CORS errors when making API requests

Problem: Cross-origin requests blocked by browser Solutions:

Configure your backend to send appropriate CORS headers
Use a proxy server during development
For production, ensure your API and frontend are on compatible domains

3. Unexpected response format

Problem: API returns wrapped responses but Restangular expects plain data Solution: Configure a response interceptor:

RestangularProvider.setResponseInterceptor(function(data, operation) {
  if (operation === 'getList') {
    return data.items; // Adjust based on your API structure
  }
  return data.data;
});

4. Authentication issues

Problem: API requires authentication but requests fail Solution: Add default headers with authentication token:

RestangularProvider.setDefaultHeaders({
  'Authorization': 'Bearer YOUR_TOKEN'
});

5. Element methods not available

Problem: Custom methods not working on elements Solution: Ensure you're using Restangular elements correctly:

// Correct: Using Restangular element
Restangular.one('users', 123).get().then(function(user) {
  user.customMethod(); // Available on elements
});

// Incorrect: Using plain object
$http.get('/users/123').then(function(response) {
  response.customMethod(); // Not available on plain objects
});

6. Testing issues

Problem: Tests failing due to Restangular configuration Solution: Configure Restangular in test setup:

beforeEach(module('restangular', function(RestangularProvider) {
  RestangularProvider.setBaseUrl('/api');
}));

7. Version compatibility issues

Problem: Restangular not working with certain AngularJS versions Note: This version of Restangular only supports AngularJS 1.x. For Angular 2+, use ngx-restangular.

8. Build failures

Problem: Grunt tasks failing Solutions:

Ensure all dependencies are installed: npm install
Check for conflicting global packages
Verify Node.js version compatibility (v4.0.0 or higher)

Getting Help

Check the GitHub issues for similar problems
Read the FAQ section in the README
Review the starter guide for basic usage patterns
Check the live demo on Plunker for working examples

How to Deploy & Use mgonto/restangular