Pandexio SDK for Ruby
Overview
This Pandexio SDK enables Ruby server applications to easily generate signed requests that can be consumed by the Pandexio REST API (https://platform.pandexio.com) and the Pandexio Hosted Model (https://hosted.pandexio.com).
Definitions
Pandexio::Request
- type - class
- attributes:
- method - required. The request HTTP verb (GET, POST, PUT, PATCH, DELETE).
- path - required. The path part of the request URL (e.g., /v2/documents/a4df7a95-d1f6-4664-b208-74568990bd15).
- query_parameters - optional. A hash containing the query parameters (e.g., { "coverSize" => "xl" }).
- headers - required. A hash containing the headers (e.g., { "Host" => "platform.pandexio.com" }). Host header must be included.
- payload - optional. UTF-8 encoded request body. Only applicable for POST, PUT, and PATCH requests.
Pandexio::SigningOptions
- type - class
- attributes:
- algorithm - required. The HMAC algorithm to use. Choose from any specified in
- Pandexio::SigningAlgorithms::PDX_HMAC_MD5 - MD5 HMAC
- Pandexio::SigningAlgorithms::PDX_HMAC_SHA1 - SHA1 HMAC
- Pandexio::SigningAlgorithms::PDX_HMAC_SHA256 - SHA256 HMAC
- Pandexio::SigningAlgorithms::PDX_HMAC_SHA384 - SHA384 HMAC
- Pandexio::SigningAlgorithms::PDX_HMAC_SHA512 - SHA512 HMAC
- mechanism - required. Specifies which signing mechanism to use. Signing mechanisms include:
- Pandexio::SigningMechanisms::QUERY_STRING - Sign the request using query string parameters
- Pandexio::SigningMechanisms::HEADER - Sign the request using headers
- domain_id - required. Public API key.
- domain_key - required. Shared secret API key used to generate HMAC signatures.
- date - required. ISO8601 date/time when the request was made.
- expires - required. Number of seconds before the request signature expires.
- originator - required. The name of the application, feature, etc. making the request.
- email_address - required. The email address of the user making the request.
- display_name - required. The display name of the user making the request.
- profile_image - optional. The profile image thumbnail, either data URL or HTTP URL of the user making the request.
- algorithm - required. The HMAC algorithm to use. Choose from any specified in
Pandexio::to_authorized_request
- type - method
- arguments
- Pandexio::Request normalized_request - A non-signed request containing information about the request to be made.
- Pandexio::SigningOptions signing_options - The details specifying how to sign the normalized_request
- result
- Pandexio::Request authorized_request - A signed request containing information about the request to be made as well as signing information as headers or query string parameters, depending on the signing_options.
Signing a Request
Take the following steps to create a signed Pandexio request.
- Create an instance of Pandexio::Request containing details of the request to be made, the normalized_request.
- Create an instance of Pandexio::SigningOptions. These signing_options specify the SDK will sign the request.
- Call Pandexio::to_authorized_request, passing in the normalized_request and the signing_options.
- Build an HTTP request using the Pandexio::Request, authorized_request, returned by Pandexio::to_authorized_request and make the HTTP request using the HTTP client of choice.
All Together
Here's an example showing the generation of a signed Pandexio request to retrieve an extra large document cover thumbnail for a given document:
require 'pandexio'
normalized_request = Pandexio::Request.new(
:method => "GET",
:path => "/v2/documents/a4df7a95-d1f6-4664-b208-74568990bd15/cover",
:query_parameters => { "coverSize" => "xl" },
:headers => { "Host" => "platform.pandexio.com" })
= Pandexio::SigningOptions.new(
:algorithm => Pandexio::SigningAlgorithms::PDX_HMAC_SHA256,
:mechanism => Pandexio::SigningMechanisms::QUERY_STRING,
:domain_id => "1234567890",
:domain_key => "asdfjklqwerzxcv",
:date => Time.utc(2015, 6, 10, 13, 22, 46),
:expires => 90,
:originator => "Demo",
:email_address => "[email protected]",
:display_name => "Terry Contoso")
= Pandexio::(normalized_request, )