# ph-restangular-api
RestAngular API Tools for PayrollHero API.

This provides a set of services and building blocks on top of Restangular to talk with
oauth based PayrollHero API Services.

# Usage
To use just depend on the 'payrollhero.api' namespace.
```
angular.module('myModule',['payrollhero.api']);
```

# Configuring

In order to configure, inject the PhApiConfig and set the token, application information, and base Uri.
```
angular.module('myModule').constant('ApiBaseUri','http://api.payrollhero.dev/api');
angular.module('myModule').run( function (PhApiConfig, PhToken) {
  PhApiConfig.configureAppInfo(
    appName: "Ph API Spec",
    appVersion: 0.1
  )
  PhApiConfig.configureToken(PhToken.token)
});
```

# Using

At it's most basic level, you can use the ```PhRestangularBase``` service.  This is a Restangular
configured service which provides standard parameters for the token, application info, and processing of
error messages returned by the API.  This is simply the global ```Restangular``` service with some additional
config attached to it.

See: https://github.com/mgonto/restangular#how-to-create-a-restangular-service-with-a-different-configuration-from-the-global-one
For more info on how PhRestangularBase is hooked into Restangular.

## PhRestangularV2, PhRestangularV3, and PhRestangularV4

These services provide access to REST resources with base urls of ```/v2```, ```/v3```, and ```/v4``` respectively.
They also provide some handy small pagination handling by adding the method ```hasMorePages``` to the returned
list object.

See: https://github.com/mgonto/restangular#collection-methods

For more info about collection methods.

Example usage of pagination...
```
angular.module('myModule').controller('MyCtrl', function($scope, EmployeesService) {

  function fetchEmployees() {
    EmployeesService.getList({page: $scope.currentPage).then( (employeesList) => {
      $scope.employees = employeesList;
      $scope.hasMoreEmployees = employeesList.hasMorePages();
    });
  };

  $scope.employees = [];
  $scope.currentPage = 1;
  $scope.hasMoreEmployees = false;
  
  fetchEmployees();
});
```

## PageInfoService
In order to properly include pagination details into the response use PageInfoService,
it will look for pagination details in the response and properly inject it into the data,
or set the default pagination params.

Example of usage...
```
mod.factory 'PhRestangularV2', (PhRestangularBase, ApiBaseUri, PageInfoService) ->
  PhRestangularBase.withConfig (config) ->
    config.setBaseUrl(ApiBaseUri + '/v2')
  .addResponseInterceptor (data, operation, what, url, response, deferred) ->
    if operation is 'getList'
      PageInfoService.addPageInfo(data, data[what])
    else
      data
```

## EmployeesService, MultipliersService, TagsService, WorksitesService, ScheduleEventsService

These services provide access to the V2 Worksites, V3 Employees, V4 Multipliers
and V4 Schedule Events API endpoints.  Please read the API documentation on what you will receive
when querying these endpoints.  There are also sub classes defined which provide handy helpers on top of these
classes built into this library.

## TimeClockingsService

The ```TimeClockingsService``` provides access to the time api.  In order to use the Time API you must configure the constant 
```TimeApiBaseUri```.

```
angular.module('myModule').constant('TimeApiBaseUri','https://time.payrollhero.com/api');
```

You may only ```POST``` to the Time API.  
See [http://docs.payrollherotimeapi.apiary.io/#reference/time-app/clockings/create-clocking]

## Building your own endpoint attachment

This library is most useful as a building block for extending and building additional connectors or talking
to other payrollhero oauth services.

For example, building your own attachment to talk to a different base Url:

```
angular.module('MyModule').service('MyAPIService', (PhRestangularBase) => {
  return PhRestangularBase.withConfig( (myConfig) => {
    myConfig.setBaseUrl("/api"); // this makes a relative url, you will talk to /api at whatever domain you served from
  });
});
```

Adding a new endpoint...

```
angular.module('MyModule').factory('V4WidgetService', (PhRestangularV4) => {
  return PhRestangularV4.service('widgets') // gives you /api/v4/widgets
});
```