Module: AtlasRb::FaradayHelper

Included in:
Authentication, Reset, Resource, User
Defined in:
lib/atlas_rb/faraday_helper.rb

Overview

HTTP transport helpers shared by every resource class.

Every Atlas request reads two environment variables:

  • ATLAS_URL — base URL of the Atlas API (e.g. https://atlas.example.edu).
  • ATLAS_TOKEN — bearer token used in the Authorization header.

Most calls also identify the acting user via a User: NUID <nuid> header. Resource classes typically pass nuid = nil (anonymous / system context); Authentication is the only place where a real NUID is currently threaded through.

The module is mixed in via extend, so its methods become class methods on the host (e.g. AtlasRb::Work.connection({})).

Instance Method Summary collapse

Instance Method Details

#connection(params, nuid = nil, idempotency_key: nil) ⇒ Faraday::Connection

Build a JSON-content Faraday connection to the Atlas API.

Examples:

Fetching a community

AtlasRb::Community.connection({}).get('/communities/abc123')

Parameters:

  • params (Hash) —

    query-string / body params to attach to the request. Resource classes use this to pass things like parent_id:, work_id:, or metadata: without manually serializing.

  • nuid (String, nil) (defaults to: nil) —

    optional Northeastern University ID to send in the User header. Defaults to nil (no NUID context).

  • idempotency_key (String, nil) (defaults to: nil) —

    optional UUID to send in the Idempotency-Key header. Used by retry-safe create flows (currently POST /works, POST /file_sets, POST /files) to deduplicate replays against the originally-created resource. Generated by the caller — this gem does not mint keys.

Returns:

  • (Faraday::Connection) —

    a connection that follows redirects and uses Faraday's default adapter.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/atlas_rb/faraday_helper.rb', line 36

def connection(params, nuid=nil, idempotency_key: nil)
  headers = {
    "Content-Type" => "application/json",
    "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
  }
  headers["User"] = "NUID #{nuid}" if nuid
  headers["Idempotency-Key"] = idempotency_key if idempotency_key

  Faraday.new(
    url: ENV.fetch("ATLAS_URL", nil),
    params: params,
    headers: headers
  ) do |f|
    f.response :follow_redirects
    f.adapter Faraday.default_adapter
  end
end

#multipart(nuid = nil, idempotency_key: nil) ⇒ Faraday::Connection

Build a multipart Faraday connection used for binary and XML uploads.

The same ATLAS_URL / ATLAS_TOKEN env vars apply. Unlike #connection, the Content-Type is set automatically by the multipart middleware, and callers pass a payload hash whose values may include Faraday::Multipart::FilePart instances.

Examples:

Posting a binary blob

payload = {
  work_id: "w-123",
  binary: Faraday::Multipart::FilePart.new(File.open("scan.pdf"),
                                            "application/octet-stream",
                                            "scan.pdf")
}
AtlasRb::Blob.multipart({}).post('/files/', payload)

Parameters:

  • nuid (String, nil) (defaults to: nil) —

    optional NUID for the User header.

  • idempotency_key (String, nil) (defaults to: nil) —

    optional UUID to send in the Idempotency-Key header. See #connection for semantics; the POST /files (Blob) create flow uses this transport.

Returns:

  • (Faraday::Connection) —

    a multipart-aware connection.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/atlas_rb/faraday_helper.rb', line 75

def multipart(nuid=nil, idempotency_key: nil)
  headers = {
    "Authorization" => "Bearer #{ENV.fetch("ATLAS_TOKEN", nil)}"
  }
  headers["User"] = "NUID #{nuid}" if nuid
  headers["Idempotency-Key"] = idempotency_key if idempotency_key

  Faraday.new(
    url: ENV.fetch("ATLAS_URL", nil),
    headers: headers
  ) do |f|
    f.request :multipart
    f.request :url_encoded
  end
end