nomis-api-client 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 266bd69217438b142dec36a1aaae5d7d9dbbc19b
-  data.tar.gz: 5a5c0b5b759c25144d0af22780e2c2f5307e773f
+  metadata.gz: 17e5a8b25e6bfe75a4301b5f7824cbc211fd83e6
+  data.tar.gz: 80503af449a148c65b7b2c7da2f10cfa38d4a61b
 SHA512:
-  metadata.gz: 5664287bec674a1d475109cfee4510335015892122a201a5558e69795696f58a8a70f49e134438f244ff52dd5be0320eae73e5581fff43761599298f231f084c
-  data.tar.gz: 65ad9e1fe13074f48fbfd980a389eae209b919335bc77169c346bf19e6bb076b81105d788dfaea9e8d2c6972914e02cc3079f60651266c1af4f5c0d39d0449c0
+  metadata.gz: 3ac008741956f3b6d65180152683b2db74c66a2eacd30606be6668f2f353c2536711136d02594cac95d213f72d3d6d3149a3a2d61b6ddad145f1854d41a6d4a6
+  data.tar.gz: d45d4fd65889266c38d73d3522e5cc20dae26d01372ad50dae5882ed225b020e7be9142f7a7b5c6786d82af61e0713c093f6536d16c286baf1c332aa1592dffa

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Crown Copyright (Ministry of Justice)
+
+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.

data/README.md

@@ -0,0 +1,118 @@
+NOMIS API Client (Ruby)
+=======================
+
+A minimal client for the [NOMIS API](http://ministryofjustice.github.io/nomis-api/)
+
+## Installation
+
+1. In your Gemfile, add:
+```ruby
+gem 'nomis-api-client'
+```
+
+2. From the console:
+```bash
+bundle install
+```
+
+## Usage
+
+### Authentication
+
+The NOMIS API uses JSON Web Token authentication, and requires all requests to provide a Bearer token in the 'Authentication' header. For example:
+
+```bash
+Authentication: Bearer eyJ(...rest of big long base64-encoded string removed...)LdRw
+```
+
+#### Generating a bearer token automatically
+
+The NOMIS API Client gem can generate a suitable token for you, given your Client Key and Client Token.
+You can provide these either directly:
+
+```ruby
+  # direct key & token parameters
+  NOMIS::API::Get.new(client_key: 'your client key', client_token: 'your client token')
+```
+
+or as paths to local files:
+
+```ruby
+  # client key & token file parameters
+  NOMIS::API::Get.new(client_key_file: 'path to your client key file', client_token_file: 'path to your client token file')
+```
+
+or as environment variables:
+```bash
+  export NOMIS_API_CLIENT_KEY_FILE=/path/to/your/client/key/file
+  export NOMIS_API_CLIENT_TOKEN_FILE=/path/to/your/client/token/file
+```
+
+#### Specifying an explicit bearer token
+
+If you'd rather provide an explicit token yourself, you can do that as follows:
+```ruby
+  # explicit auth_token parameter
+  NOMIS::API::Get.new(auth_token:'your bearer token')
+```
+
+#### Manually generating a bearer token
+
+You can generate a bearer token without making a request as follows:
+
+```ruby
+  # Manually generating a bearer token
+  NOMIS::API::AuthToken.new(client_key: 'your client key', client_token: 'your client token').bearer_token
+
+### Environment (preprod/prod)
+
+The NOMIS API has two endpoints avaiable:
+- production ('prod') at https://noms-api.service.justice.gov.uk/nomisapi/
+- pre-production ('preprod') at https://noms-api-preprod.dsd.io/nomisapi/. 
+
+To tell the API client to use one or the other, either provide a base_url parameter:
+```ruby
+  # direct base_url parameter
+  NOMIS::API::Get.new(base_url: 'https://noms-api.service.justice.gov.uk/nomisapi/', ...)
+```
+
+or the environment variable NOMIS_API_BASE_URL:
+```ruby
+  #  base URL environment variable
+  export NOMIS_API_BASE_URL='https://noms-api.service.justice.gov.uk/nomisapi/'
+```
+
+
+## Making a request
+
+To make an API request, first construct a Get or Post object, providing:
+
+- path: the path of the endpoint you are requesting (required)
+
+- params: a hash of params you are passing (optional)
+- any authentication parameters (optional) - see ['Authentication'](#Authentication) above
+- base_url: the base URL (optional) - see ['Environment'](#Environment) above
+
+```ruby
+  # construct a 'lookup active offender' request
+  req = NOMIS::API::Get.new(path: 'lookup/active_offender', params: {noms_id:'A12345BC', date_of_birth:'1966-05-29'})
+
+  # make the request
+  response = req.execute
+```
+
+The response will be a ParsedResponse object, encapsulating the raw response, the HTTP status, and the data parsed as JSON:
+
+```ruby
+=> #<NOMIS::API::ParsedResponse:0x007ffbf35a1238 @raw_response=#<Net::HTTPOK 200 OK readbody=true>, @data={"found"=>true, "offender"=>{"id"=>1234567}}>
+
+bundle :027 > response.status
+ => "200" 
+
+bundle :028 > response.data
+ => {"found"=>true, "offender"=>{"id"=>1820518}} 
+```
+
+## API Documentation
+
+For full details on the supported endpoints, see the [API documentation](http://ministryofjustice.github.io/nomis-api/)

data/bin/generate_bearer_token

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby 
+#
+# Usage:
+# generate_bearer_token client_key_file client_token_file
+#
+
+require 'nomis_api_client_ruby'
+
+def usage
+  output = <<-END
+  Usage:
+    generate_bearer_token client_key_file client_token_file
+  
+  Useful environment variables:
+
+  NOMIS_API_IAT_FUDGE_FACTOR
+  - a positive/negative integer adjustment which will be added to 
+    the current time to generate the 'iat' timestamp for the 
+    token
+    If you recieve an error message from the api saying
+    'iat skew too large', you can provide this to bring your system
+    time within +/-10s of the API gateway.
+    e.g.
+     NOMIS_API_IAT_FUDGE_FACTOR=-5 generate_bearer_token ~/my.key ~/my.token
+
+END
+end
+
+raise usage unless $ARGV.size == 2
+
+token = NOMIS::API::AuthToken.new(client_key_file: $1, client_token_file: $2).bearer_token
+puts token
+
+

data/lib/nomis/api/auth_token.rb

@@ -0,0 +1,86 @@
+require 'base64'
+require 'jwt'
+require 'openssl'
+
+module NOMIS
+  module API
+    # Encapsulates the complexity of generating a JWT bearer token
+    class AuthToken
+      attr_accessor :client_token, :client_key, :iat_fudge_factor
+
+      # iat_fudge_factor allows you to correct for time drift between your
+      # client and the target server.
+      # For instance, if the server time is more than 10s in the future, it
+      # will reject any client-generated bearer tokens on the grounds of
+      # 'iat skew too large' (the timestamp in your payload is too old)
+      # In that case, you can pass an iat_fudge_factor of, say, 5, to generate a
+      # timestamp tagged 5s into the future and bring it back within the
+      # acceptable range.
+      def initialize(params = {})
+        self.client_key = OpenSSL::PKey::EC.new( params[:client_key] \
+                            || default_client_key(params)
+                          )
+        self.client_token = params[:client_token] \
+                          || default_client_token(params)
+
+        self.iat_fudge_factor = default_iat_fudge_factor(params)
+      end
+
+      def bearer_token
+        validate_keys!
+
+        auth_token = JWT.encode(payload, client_key, 'ES256')
+
+        "Bearer #{auth_token}"
+      end
+
+      def payload
+        {
+          iat: Time.now.to_i + iat_fudge_factor,
+          token: client_token
+        }
+      end
+
+      # Validate that the supplied private key matches the token's public key.
+      # Obviously this step is optional, but when testing locally it's
+      # easy to get one's private keys in a muddle, and the API gateway's
+      # error message can only say that the generated JWT token does not
+      # validate.
+      def validate_keys!
+        client_pub = OpenSSL::PKey::EC.new client_key
+        client_pub.private_key = nil
+        client_pub_base64 = Base64.strict_encode64(client_pub.to_der)
+
+        expected_client_pub = JWT.decode(client_token, nil, nil)[0]['key']
+
+        unless client_pub_base64 == expected_client_pub
+          raise 'Incorrect private key supplied ' \
+                + '(does not match public key within token)'
+        end
+      end
+
+      protected
+
+      def default_client_key(params={})
+        read_client_key_file(params[:client_key_file] || ENV['NOMIS_API_CLIENT_KEY_FILE'])
+      end
+      
+      def default_client_token(params={})
+        read_client_key_file(params[:client_token_file] || ENV['NOMIS_API_CLIENT_TOKEN_FILE'])
+      end
+
+      def default_iat_fudge_factor(params={})
+        ENV['NOMIS_API_IAT_FUDGE_FACTOR'].to_i || 0
+      end
+
+      def read_client_token_file(path)
+        File.open(File.expand_path(path), 'r').read.chomp('')
+      end
+
+      def read_client_key_file(path)
+        File.open(File.expand_path(path), 'r').read
+      end
+
+    end
+  end
+end

data/lib/nomis/api/get.rb

@@ -0,0 +1,47 @@
+require 'uri'
+require 'net/http'
+require 'pp'
+require 'byebug'
+
+require 'nomis/api/auth_token'
+require 'nomis/api/parsed_response'
+
+module NOMIS
+  module API
+    # Convenience wrapper around an API call
+    # Manages defaulting of params from env vars,
+    # and parsing the returned JSON
+    class Get
+      attr_accessor :params, :auth_token, :base_url, :path
+
+      def initialize(opts={})
+        self.auth_token = opts[:auth_token] || default_auth_token(opts)
+        self.base_url   = opts[:base_url] || ENV['NOMIS_API_BASE_URL']
+        self.params = opts[:params] || {}
+        self.path = opts[:path]
+      end
+
+      def execute
+        uri = URI.join(base_url, path)
+        uri.query = URI.encode_www_form(params)
+
+        req = Net::HTTP::Get.new(uri)
+        req['Authorization'] = auth_token
+
+        ParsedResponse.new(get_response(req))
+      end
+
+      protected
+
+      def default_auth_token(params={})
+        ENV['NOMIS_API_AUTH_TOKEN'] || NOMIS::API::AuthToken.new(params).bearer_token
+      end
+
+      def get_response(req)
+        http = Net::HTTP.new(req.uri.hostname, req.uri.port)
+        http.use_ssl = (req.uri.scheme == "https")
+        http.request(req)
+      end
+    end
+  end
+end

data/lib/nomis/api/parsed_response.rb

@@ -0,0 +1,23 @@
+require 'json'
+
+module NOMIS
+  module API
+    # decorates a Net::HTTP response with a data method,
+    # which parses the JSON in the response body
+    class ParsedResponse
+      attr_accessor :raw_response, :body, :status, :data
+
+      def initialize(raw_response)
+        self.raw_response = raw_response
+        self.data = JSON.parse(raw_response.body)
+      end
+
+      def body
+        raw_response.body
+      end
+      def status
+        raw_response.code
+      end
+    end
+  end
+end

data/lib/nomis/api/post.rb

@@ -0,0 +1,56 @@
+require 'uri'
+require 'net/http'
+require 'pp'
+
+require 'nomis/api/auth_token'
+require 'nomis/api/parsed_response'
+
+module NOMIS
+  module API
+    # Convenience wrapper around an API call
+    # Manages defaulting of params from env vars,
+    # and parsing the returned JSON
+    class Post
+      attr_accessor :params, :auth_token, :base_url, :path
+
+      def initialize(opts={})
+        self.auth_token = opts[:auth_token] || default_auth_token(opts)
+        self.base_url   = opts[:base_url] || ENV['NOMIS_API_BASE_URL']
+        self.params = opts[:params]
+        self.path = opts[:path]
+      end
+
+      def execute
+        uri = URI.join(base_url, path)
+
+        req = Net::HTTP::Post.new(uri)
+        req['Authorization'] = auth_token
+        req['Accept'] = 'application/json, */*'
+        req['Content-type'] = 'application/json'
+
+        ParsedResponse.new(post_response(req))
+      end
+
+      protected
+
+      def default_auth_token(params={})
+        ENV['NOMIS_API_AUTH_TOKEN'] || NOMIS::API::AuthToken.new(params).bearer_token
+      end
+
+
+      def post_response(req)
+        http = Net::HTTP.new(req.uri.hostname, req.uri.port)
+        http.use_ssl = (req.uri.scheme == 'https')
+        req.body = params.to_json
+        http.request(req)
+      end
+
+      def stringify_hash(data)
+        h={}
+        data.each{|k,v| h[k.to_s] = v }
+        h
+      end
+
+    end
+  end
+end

data/lib/nomis/api.rb

@@ -0,0 +1,4 @@
+require 'nomis/api/auth_token'
+require 'nomis/api/get'
+require 'nomis/api/parsed_response'
+require 'nomis/api/post'

data/lib/nomis_api_client_ruby.rb

@@ -1 +1 @@
-require_relative './nomis/api'
+require 'nomis/api'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nomis-api-client
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Al Davidson
@@ -40,10 +40,19 @@ dependencies:
         version: '0'
 description: A minimal Ruby client for the [NOMIS API](http://ministryofjustice.github.io/nomis-api/)
 email: alistair.davidson@digital.justice.gov.uk
-executables: []
+executables:
+- generate_bearer_token
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- bin/generate_bearer_token
+- lib/nomis/api.rb
+- lib/nomis/api/auth_token.rb
+- lib/nomis/api/get.rb
+- lib/nomis/api/parsed_response.rb
+- lib/nomis/api/post.rb
 - lib/nomis_api_client_ruby.rb
 homepage: http://rubygems.org/gems/nomis_api_client_ruby
 licenses: