Ruby Federal Data SDK

Adding the SDK to Your Project

Add SDK files to your project

Extract the zipped SDK folder or grab the Git repository.
Copy the DOLDataSDK.rb file into your project.

Install Required Gems

Install the required gems:

json

Using the SDK

Reference the SDK in your source file

In the source files that will make data requests add the following require:

require "./GOVDataSDK"

Making API Calls

The GOV::DataRequest class is used to make API calls. It requires a context object to be passed to its constructor in order to get the API key and URL information needed for the requests. The GOV::DataContext is the context class used to hold this information.

You can also pass arguments to the API call by adding them to a Hash as key/value pairs and passing it as the second argument of the #call_api method. Valid arguments are defined later in this document.

In order to make requests:

Instantiate a GOV::DataContext object
Instantiate a GOV::DataRequest object and initialize it with the context
Create a Hash and store all the API arguments as key/value pairs.
Call the #call_api method, passing the API name and the arguments (leave off the arguments if there are no arguments)
Provide #call_api with a block to be executed when the results have been processed.

Sample code to make requests for standard DOL API datasets:

require "./GOVDataSDK"

#Instantiate  GOV Data context object
#This  object stores the API information required to make requests
context = GOV::DataContext.new "http://api.dol.gov", "your-api-key", "your-shared-secret"

#Instantiate  new request object. Pass the context that contains all the API key info
request = GOV::DataRequest.new context

#API  you want to fetch data from
method = "FORMS/Agencies"

#Build Hash arguments
#Example to retrieve top 10 records and just get one field. 
arguments = { :top => 10, :select => "AgencyName" }

#Make API call
request.call_api method, arguments do |results, error|
    if error
        #handle error
    else
        #handle success
    end
end

Sample code to make requests for DOL Service Operation (e.g Summer Jobs Plus) :

require "./GOVDataSDK"

#Instantiate  DOL Data context object
#This  object stores the API information required to make requests
context = DOL::DataContext.new "http://api.dol.gov", "your-api-key", "your-shared-secret"

#Instantiate  new request object. Pass the context that contains all the API key info
request = GOV::DataRequest.new context

#API  you want to fetch data from
method = "SummerJobs/getJobsListing"

#Build Hash arguments
#Example to retrieve top 10 records and just get one field. 
arguments = { :format => '\'json\'', :query => '\'farm\'', :region => '', :locality => '', :skipCount => '1' }

#Make API call
request.call_api method, arguments do |results, error|
    if error
        #handle error
    else
        #handle success
    end
end

The #call_api triggers the SDK to process the request, add authorization headers and execute the block with the results or with an error message. This occurs in a seperate thread, so as not to block the main thread. The GOV::DataRequest#wait_until_finished method should be called if the program needs to be halted until the request processes.

API Method Arguments

Standard DOL API datasets

top

The top argument is used to specify the number of records to be returned.

Example:

args = { :top => 2 }

skip

The skip argument specifies that you want the service to skip a specified number of results. This argument in combination with top, serve as the basis to implement pagination.

Example:

#Return records 21-30
args = { :top => 10, :skip => 20 }

select

The select argument allows you to specify the exact columns that you want the API to return. Separate them with commas if there is more than one.

In order to save bandwidth, it is always a good idea to add a select clause to most requests and retrieve the columns needed for a specific function. Some datasets can contain dozens of columns and the performance of your app can be impacted if you always return all of the columns. This is even more important in mobile applications because of device memory limitations, possible slow network speeds, and data usage caps imposed by carriers.

Example:

#Select the AgencyId and AgencyFormNumber columns
args = { :select => "AgencyId,AgencyFormNumber" }

orderby

Use the orderby argument to sort the data by one or more columns. Separate them with commas if there is more than one.

#Order by the AgencyFormNumber column
args = { :orderby => "AgencyFormNumber" }

filter

The filter argument is used to add filters to the API query. For example, you can filter results where a specific column is equal to a string provided.

The API recognizes the following comparison keywords:
eq – Equal to
ne – Not Equal to
gt – Greater than
lt – Less than
ge – Greater than or equal to
le – Less than or equal to

For string comparisons enclose any multiple word string in single quotes. For example: 'Legal Identity Report'

More than one filter can be specified by joining them with the and/or keywords. Separate filters with parenthesis.
For example: (AgencyId eq 'MSHA') and (Title eq 'Legal Identity Report') retrieves the records where the value in the AgencyId column is equal to 'MSHA' and the value for the Title column is equal to 'Legal Identity Report'.

Example:

args = { :filter => "(AgencyId eq 'MSHA') and (Title eq 'Legal Identity Report')" }

DOL Service Operation for Summer Jobs Plus

To use the Service Operations API the Operation name and parameters need to be supplied using the data services format. Each String typed parameter must be surrounded in quotes in order to work correctly. These quotes are then Url encoded and passed to the Service Operation. Each integer typed parameter must be entered without quotes in order to work correctly.Each parameter that is assigned null should be left blank.

format

The format argument allows you to specify the format that the results string will be returned. If format argument is not passed with request then result will be returned in json format by default. Following are the supported format of results string.

Format Codes:
json ( Default )
xml
atom

Example:

args = { '\'json\'' };

query

The query argument will be used to find matching job listings. This is required if region or locality are not provided.

Example:

args = { '\'json\'',:query => '\'farm\'' };

region

The region argument will be used to filter jobs listings by the state name or abbreviation. This is required if query or locality are not provided.

Example:

args = { '\'json\'',:query => '\'farm\'',:region => ''};

locality

The region argument will be used to filter jobs listings by The city name. This is required if query or region are not provided.

Example:

args = { '\'json\'',:query => '\'farm\'',:region => '', :locality=> '' };

skipCount

The skipCount argument will be used to specify the number of records to skip ahead from the first recor.Valid range of 1-99 and it required.

Example:

args = { '\'json\'',:query => '\'farm\'',:region => '', :locality=> '' ,:skipCount => '1'};

Licenses

The DOLData classes (the classes within the DOL module) are released to the Public Domain.

This SDK makes use of other libraries that are licensed differently. Please read them carefully.

json gem

Ruby License

ruby-hmac gem

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.