Ruby wrapper classes around the miiCard API
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
LICENCE.TXT
README.md
miiCardConsumers.gemspec

README.md

api-wrappers-ruby

Ruby wrapper classes around the miiCard API.

This repository houses the source for the latest version of the miiCard Consumers library available on RubyGems.org.

What is miiCard

miiCard lets anybody prove their identity to the same level of traceability as using a passport, driver's licence or photo ID. We then allow external web applications to ask miiCard users to share a portion of their identity information with the application through a web-accessible API.

What is the library for?

miiCard's API is an OAuth-protected web service supporting SOAP, POX and JSON - documentation is available. The library wraps the JSON endpoint of the API, making it easier to make the required OAuth signed requests.

You can obtain a consumer key and secret from miiCard by contacting us on our support form, including the details listed on the developer site.

Pull the library into your own application by downloading the latest released version from RubyGems.org.

Usage

You'll need to implement your own OAuth exchange with miiCard.com's OAuth endpoint to obtain an access token and secret for a user.

Accessing the Claims API

Once you've got your consumer key and secret, access token and access token secret you can instantiate an API wrapper:

api = MiiCardOAuthClaimsService.new("consumer_key", "consumer_secret", "access_token", "access_token_secret")

Then make calls against it simply:

user_profile_response = api.get_claims().data

user_first_name = user_profile_response.data.first_name

Financial API

Accessing the Financial API is the same, but with a different wrapper type - MiiCardOAuthFinancialService:

api = MiiCardOAuthFinancialService.new("consumer_key", "consumer_secret", "access_token", "access_token_secret")

Directory API

Unlike the Claims and Financial APIs, the Directory API is a public lookup service that requires no special OAuth steps to access:

api = MiiCardDirectoryService.new()

Test harness

There is a Rails test harness that provides a little sample code as well as letting you exercise the APIs and check that OAuth tokens that you've obtained are valid, also available on GitHub along with instructions on how to run and use it.

Mapping from API data types

The following list is provided as a convenient cheat-sheet, and maps the API's methods and data types to their equivalents in the Ruby wrapper library classes.

Methods

Claims API (documentation link)

API methodRuby equivalent (given `api` instance of `MiiCardOAuthClaimsService`)
AssuranceImageapi.assurance_image(type)
GetCardImageapi.get_card_image(snapshot_id, show_email_address, show_phone_number, format)
GetClaimsapi.get_claims()
GetIdentitySnapshotapi.get_identity_snapshot(snapshot_id)
GetIdentitySnapshotPdfapi.get_identity_snapshot_pdf(snapshot_id)
GetIdentitySnapshotDetailsapi.get_identity_snapshot_details()
Or, for a specific snapshot:
api.get_identity_snapshot_details(snapshot_id)
IsSocialAccountAssuredapi.is_social_account_assured(social_account_id, social_account_type)
IsUserAssuredapi.is_user_assured()

Financial API (documentation link)

API methodRuby equivalent (given `api` instance of `MiiCardOAuthFinancialService`)
IsRefreshInProgressapi.is_refresh_in_progress()
IsRefreshInProgressCreditCardsapi.is_refresh_in_progress_credit_cards()
RefreshFinancialDataapi.refresh_financial_data()
RefreshFinancialDataCreditCardsapi.refresh_financial_data_credit_cards()
GetFinancialTransactionsapi.get_financial_transactions()
GetFinancialTransactionsCreditCardsapi.get_financial_transactions_credit_cards()

Directory API (documentation link)

Search criterionRuby equivalent (given `api` instance of MiiCardDirectoryService)
Anyapi.find_by(criterion, criterion_value, hashed = false)
Usernameapi.find_by_username(username, hashed = false)
Emailapi.find_by_email(email, hashed = false)
Phoneapi.find_by_phone(phone, hashed = false)
Twitterapi.find_by_twitter(twitter_handle_or_url, hashed = false)
Facebookapi.find_by_facebook(facebook_url, hashed = false)
LinkedInapi.find_by_linkedin(linkedin_www_url, hashed = false)
Googleapi.find_by_google(google_handle_or_url, hashed = false)
LiveID/Microsoft IDapi.find_by_microsoft_id(microsoft_id_url, hashed = false)
eBayapi.find_by_ebay(ebay_handle_or_my_ebay_url, hashed = false)
Veritas Vitaeapi.find_by_veritas_vitae(vv_number_or_profile_url, hashed = false)

If you need to hash an identifier you can use the MiiCardDirectoryService.hash_identifier(identifier) static function. This won't normalise the identifier, but will at least lowercase it before hashing - see the Directory API documentation for details on normalisation steps.

Data types - Claims API

AuthenticationDetails (documentation link)

API data-type propertyRuby equivalent (given `details` instance of `AuthenticationDetails`)
AuthenticationTimeUtcdetails.authentication_time_utc
SecondFactorTypedetails.second_factor_type
SecondFactorProviderdetails.second_factor_provider
Locationsdetails.locations

AuthenticationTokenType enumeration type (documentation link)

API data-type propertyRuby equivalent
NoneAuthenticationTokenType.NONE
SoftAuthenticationTokenType.SOFT
HardAuthenticationTokenType.HARD

EmailAddress (documentation link)

API data-type propertyRuby equivalent (given `email` instance of `EmailAddress`)
DisplayNameemail.display_name
Addressemail.address
IsPrimaryemail.is_primary
Verifiedemail.verified

GeographicLocation (documentation link)

API data-type propertyRuby equivalent (given `location` instance of `GeographicLocation`)
LocationProviderlocation.location_provider
Latitudelocation.latitude
Longitudelocation.longitude
LatLongAccuracyMetreslocation.lat_long_accuracy_metres
ApproximateAddresslocation.approximate_address

Identity (documentation link)

API data-type propertyRuby equivalent (given `identity` instance of `Identity`)
Sourceidentity.source
UserIdidentity.user_id
ProfileUrlidentity.profile_url
Verifiedidentity.verified

IdentitySnapshot (documentation link)

API data-type propertyRuby equivalent (given `snapshot` instance of `IdentitySnapshot`)
Detailssnapshot.details
Snapshotsnapshot.snapshot

IdentitySnapshotDetails (documentation link)

API data-type propertyRuby equivalent (given `snapshot_details` instance of `IdentitySnapshotDetails`)
SnapshotIdsnapshot_details.snapshot_id
Usernamesnapshot_details.username
TimestampUtcsnapshot_details.timestamp_utc
WasTestUsersnapshot_details.was_test_user

MiiApiCallStatus enumeration type (documentation link)

API data-type propertyRuby equivalent
SuccessMiiApiCallStatus.SUCCESS
FailureMiiApiCallStatus.FAILURE

MiiApiErrorCode enumeration type (documentation link)

API data-type propertyRuby equivalent
SuccessMiiApiCallStatus.SUCCESS
UnknownSearchCriterionMiiApiCallStatus.UNKNOWN_SEARCH_CRITERION
NoMatchesMiiApiCallStatus.NO_MATCHES
AccessRevokedMiiApiCallStatus.ACCESS_REVOKED
UserSubscriptionLapsedMiiApiCallStatus.USER_SUBSCRIPTION_LAPSED
TransactionalSupportDisabledMiiApiCallStatus.TRANSATIONAL_SUPPORT_DISABLED
FinancialDataSupportDisabledMiiApiCallStatus.FINANCIAL_DATA_SUPPORT_DISABLED
DevelopmentTransactionalSupportOnlyMiiApiCallStatus.DEVELOPMENT_TRANSACTIONAL_SUPPORT_ONLY
InvalidSnapshotIdMiiApiCallStatus.INVALID_SNAPSHOT_ID
BlacklistedMiiApiCallStatus.BLACKLISTED
ProductDisabledMiiApiCallStatus.PRODUCT_DISABLED
ProductDeletedMiiApiCallStatus.PRODUCT_DELETED
ExceptionMiiApiCallStatus.EXCEPTION

MiiApiResponse (documentation link)

API data-type propertyRuby equivalent (given `response` instance of `MiiApiResponse`)
Statusresponse.status
ErrorCoderesponse.error_code
ErrorMessageresponse.error_message
Dataresponse.data
IsTestUserresponse.is_test_user

MiiUserProfile (documentation link)

API data-type propertyRuby equivalent (given `profile` instance of `MiiUserProfile`)
Salutationprofile.salutation
FirstNameprofile.first_name
MiddleNameprofile.middle_name
LastNameprofile.last_name
DateOfBirthprofile.date_of_birth
Ageprofile.age
PreviousFirstNameprofile.previous_first_name
PreviousMiddleNameprofile.previous_middle_name
PreviousLastNameprofile.previous_last_name
LastVerifiedprofile.last_verified
ProfileUrlprofile.profile_url
ProfileShortUrlprofile.profile_short_url
CardImageUrlprofile.card_image_url
EmailAddressesprofile.email_addresses
Identitiesprofile.identities
PhoneNumbersprofile.phone_numbers
PostalAddressesprofile.postal_addresses
Qualificationsprofile.qualifications
WebPropertiesprofile.web_properties
IdentityAssuredprofile.identity_assured
HasPublicProfileprofile.has_public_profile
PublicProfileprofile.public_profile
CreditBureauVerificationprofile.credit_bureau_verification

PhoneNumber (documentation link)

API data-type propertyRuby equivalent (given `phone` instance of `PhoneNumber`)
DisplayNamephone.display_name
CountryCodephone.country_code
NationalNumberphone.national_number
IsMobilephone.is_mobile
IsPrimaryphone.is_primary
Verifiedphone.verified

PostalAddress (documentation link)

API data-type propertyRuby equivalent (given `address` instance of `PostalAddress`)
Houseaddress.house
Line1address.line1
Line2address.line2
Cityaddress.city
Regionaddress.region
Codeaddress.code
Countryaddress.country
IsPrimaryaddress.is_primary
Verifiedaddress.verified

Qualification (documentation link)

API data-type propertyRuby equivalent (given `qualification` instance of `Qualification`)
Typequalification.type
Titlequalification.title
DataProviderqualification.data_provider
DataProviderUrlqualification.data_provider_url

QualificationType enumeration type (documentation link)

API data-type propertyRuby equivalent
AcademicQualificationType.ACADEMIC
ProfessionalQualificationType.PROFESSIONAL

WebProperty (documentation link)

API data-type propertyRuby equivalent (given `property` instance of `WebProperty`)
DisplayNameproperty.display_name
Identifierproperty.identifier
Typeproperty.type
Verifiedproperty.verified

WebPropertyType enumeration type (documentation link)

API data-type propertyRuby equivalent
DomainWebPropertyType.DOMAIN
WebsiteWebPropertyType.WEBSITE

Model\CreditBureauVerification (documentation link)

API data-type propertyRuby equivalent (given `verification` instance of CreditBureauVerification)
Dataverification.data
LastVerifiedverification.last_verified

Model\CreditBureauRefreshStatus (documentation link)

API data-type propertyRuby equivalent (given `status` instance of `CreditBureauRefreshStatus`)
Statestatus.state

Data types - Financial API

FinancialAccount (documentation link)

API data-type propertyRuby equivalent (given `account` instance of `FinancialAccount`)
AccountNameaccount.account_name
Holderaccount.holder
SortCodeaccount.sort_code
AccountNumberaccount.account_number
Typeaccount.type
FromDateaccount.from_date
LastUpdatedUtcaccount.last_updated_utc
ClosingBalanceaccount.closing_balance
DebitsSumaccount.debits_sum
DebitsCountaccount.debits_count
CreditsSumaccount.credits_sum
CreditsCountaccount.credits_count
CurrencyIsoaccount.currency_iso
Transactionsaccount.transactions

FinancialCreditCard (documentation link)

API data-type propertyRuby equivalent (given `credit_card` instance of `FinancialCreditCard`)
AccountNamecredit_card.account_name
Holdercredit_card.holder
AccountNumbercredit_card.account_number
Typecredit_card.type
FromDatecredit_card.from_date
LastUpdatedUtccredit_card.last_updated_utc
CreditLimitcredit_card.credit_limit
RunningBalancecredit_card.running_balance
DebitsSumcredit_card.debits_sum
DebitsCountcredit_card.debits_count
CreditsSumcredit_card.credits_sum
CreditsCountcredit_card.credits_count
CurrencyIsocredit_card.currency_iso
Transactionscredit_card.transactions

FinancialProvider (documentation link)

API data-type propertyRuby equivalent (given `provider` instance of `FinancialProvider`)
ProviderNameprovider.provider_name
FinancialAccountsprovider.financial_accounts

FinancialRefreshStatus (documentation link)

API data-type propertyRuby equivalent (given `status` instance of `FinancialRefreshStatus`)
Statestatus.state

FinancialTransaction (documentation link)

API data-type propertyRuby equivalent (given `transaction` instance of `FinancialTransaction`)
Datetransaction.date
AmountCreditedtransaction.amount_credited
AmountDebitedtransaction.amount_debited
Descriptiontransaction.description
IDtransaction.id

MiiFinancialData (documentation link)

API data-type propertyRuby equivalent (given `data` instance of `MiiFinancialData`)
FinancialProvidersdata.financial_providers

RefreshState enumeration type (documentation link)

API data-type propertyRuby equivalent
UnknownRefreshState.UNKNOWN
DataAvailableRefreshState.DATA_AVAILABLE
InProgressRefreshState.IN_PROGRESS

Dependencies

The library takes a dependency on:

Contributing

  • Use GitHub issue tracking to report bugs in the library
  • If you're going to submit a patch, please base it off the development branch - the master reflects the latest version published to RubyGems.org but may not necessarily be bleeding-edge

Licence

Copyright (c) 2012, miiCard Limited All rights reserved.

http://opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of miiCard Limited nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.