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
});