node-madgex
A node.js client for Madgex web services.
About
Madgex's web services are split between RESTful and SOAP APIs. This module currently supports only a subset of the APIs, but we would be delighted to receive pull requests for the methods that are missing.
The current set of supported web services is
REST API
- getinfo
- employer
- myjobs
Billing API
- AddBilledJob
- AddRecruiterV2
- GetCategories
- GetCategoryTerms
- GetLocations
- UpdateBilledJob
- UpdateRecruiterWithBillingID
- AddPrePaidCredits
- CheckRecruiterExistsV2
The REST API
Usage
var madgex = var client = madgex clientrestApi
API methods usually accept a params hash and a completion callback with (err, data, result) signature;
Promises
As an alternative to the completion callback you can use promises as well. Api methods return with a promise that resolves after the completion callback (if one is present).
client ;
Chain'em
Promised values are easy to compose:
clientjobinfo ;
Service Description
The RESTful client API is dynamically built by code from the service description config file. Extend this to add new functions to the API. (/lib/rest-api-service-description.json)
Service Methods
jobinfo(params, done)
Displays information about a job
params
a hash with the following fields
field | type,info |
---|---|
jobid | integer, required |
jobinfo.search(params, done)
Searches in the job database
params
field | type,info |
---|---|
keywords | free text with boolean expressions allowed, optional |
dateFrom | ISO format date |
dateTo | ISO format date |
...and much more. refer to the Madgex REST documentation for full set of params.
jobinfo.search.full(params, done)
Same as search but returns full dataset
jobinfo.search.facets(params, done)
Return search refiners for a search result. Params are same as in search()
employer(params, done)
Displays information about am employer
params
a hash with the following fields
field | type,info |
---|---|
id | integer, required |
employer.search(params, done)
Searches in the employer database
myjobs.add(params, done)
myjobs.delete(params, done)
The SOAP API
Usage
var madgex = var client = madgex clientsoapApibillingApi
Each billingApi method takes an optional parameters object and typical callback. You can determine the available parameters names by inspecting the equivalent methods handlebars template (see ./lib/soap-templates/*.hbs). These are camel cased equivalents to the elements specified in the Madgex Billing API documentation. Working out which parameters are required and what their values should be requires a degree of experience.
Responses stripped of their SOAPiness and converted to camelCased json. Integers, floats and booleans are parsed, so instead of
false true 105 Hours
you'll receive
Error handling
In the event of an HTTP error, the err object passed to your callback will be blessed with a 'statusCode' property. In the event ofa SOAP Fault, the err object will additionally be blessed with 'faultCode' and 'faultString' properties.
Adding more SOAP API methods
Adding more API methods is easy
- Fork and clone node-madgex
- Generate a real request and response using your tool of choice (SoapUI, curl, etc)
- Convert the request to a handlbars template and save it in lib/soap-templates/MethodName.hbs,
- Save the response in test/replies/soap/MethodName.ok.xml
- Update lib/soap-api-service-description.json
- Add one or more test cases
- Submit a PR