A set of API adapters to work with the GOV.UK APIs
Ruby Shell
Latest commit b487c80 Jan 16, 2017 @tijmenb tijmenb committed on GitHub Merge pull request #651 from alphagov/document_publishing_api_test_he…

Add minimal yardoc for publishing api test helpers
Failed to load latest commit information.
lib Add minimal yardoc for publishing api test helpers Jan 13, 2017
test Update pact Jan 3, 2017
.gitignore Document a little more of `GdsApi::PublishingApiV2` Apr 18, 2016
.rubocop.yml Fix linting errors Dec 8, 2016
.yardopts Generate docs only for documented APIs Nov 17, 2016
CHANGELOG.md Bump version to 39.0.0 Dec 22, 2016
CONTRIBUTING.md Change all instances of unified_search to search Aug 31, 2016
Gemfile Use latest version of rack-cache Feb 10, 2016
Jenkinsfile Make git credentials available when publishing gem Jan 6, 2017
LICENCE.txt Correct copyright notice Feb 16, 2015
README.md Remove deprecated 404 behaviour Dec 1, 2016
Rakefile Fix linting errors Dec 8, 2016
docs-intro.html Generate docs only for documented APIs Nov 17, 2016
gds-api-adapters.gemspec Remove test files from the built gem Dec 29, 2016
jenkins.sh Make the Jenkins build fail when it encounters errors at any step Dec 21, 2016


GDS API Adapters

A set of API adapters to work with the GDS APIs.

Example usage:

require 'gds_api/rummager'
rummager = GdsApi::Rummager.new(Plek.new.find('rummager'))
results = rummager.search(q: "taxes")

Example adapters for frequently used applications:


Each HTTP request can be logged as JSON. Example:


By default we log to a NullLogger since we don't want to pollute your test results or logs. To log output you'll want to set GdsApi::Base.logger to something that actually logs:

GdsApi::Base.logger = Logger.new("/path/to/file.log")

Setting the timeout

By default the JsonClient timeout is set to 4 seconds. If this is exceeded a GdsApi::TimedOutException will be raised. Individual clients may decide to override this timeout. Alternatively, you can override this in the application that uses the adapter with:

Services.publishing_api.client.options[:timeout] = number_of_seconds

In most cases, there is an upper-limit of 30 seconds imposed by the app server or Nginx. If your requests are taking this long, you should probably be looking into other options to lower the response time.

Middleware for request tracing

We set a unique header at the cache level called Govuk-Request-Id, and also set a header called Govuk-Original-Url to identify the original URL requested. If apps make API requests in order to serve a user's request, they should pass on these headers, so that requests can be traced across the entire GOV.UK stack.

The GdsApi::GovukHeaderSniffer middleware takes care of this. This gem contains a railtie that configures this middleware for Rails apps without extra effort. Other Rack-based apps should opt-in by adding these lines to your config.ru:

use GdsApi::GovukHeaderSniffer, 'HTTP_GOVUK_REQUEST_ID'
use GdsApi::GovukHeaderSniffer, 'HTTP_GOVUK_ORIGINAL_URL'

Middleware for identifying authenticated users

Applications can make use of user-based identification for additional authorisation when making API requests. Any application that is using gds-sso for authentication can set an additional header called 'X-Govuk-Authenticated-User' to identify the currently authenticated user ID. This will automatically be picked up by the GdsApi::GovukHeaderSniffer middleware in Rails applications and sent with API requests so that the downstream service can optionally use the identifier to perform authorisation on the request. This will be used by content-store as a mechanism to only return access-limited content to authenticated and authorised users.

App-level Authentication

The API Adapters currently support either HTTP Basic or OAuth2 (bearer token) authentication. This allows an application to identify itself to another where required. This is currently used by the GdsApi::Panopticon::Registerer adapter, which expects a constant called PANOPTICON_API_CREDENTIALS to be defined that identifies the calling application to Panopticon:


Test Helpers

There are also test helpers for stubbing various requests in other apps. Example usage of the panopticon helper:

In test_helper.rb:

require 'gds_api/test_helpers/panopticon'

class ActiveSupport::TestCase
  include GdsApi::TestHelpers::Panopticon

In the test:

panopticon_has_metadata('id' => 12345, 'need_ids' => [need.id],
  'slug' => 'my_slug')


Some of the helpers come with additional dependencies that you'll need to have installed and configured in your consuming app/lib.

At time of writing, these are:


See RubyDoc for some limited documentation.

To run a Yard server locally to preview documentation, run:

$ bundle exec yard server --reload


Released under the MIT Licence, a copy of which can be found in the file LICENCE.