ph-restangular-api v0.3.1
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
});