midas.client — energy.grid-coordination/clj-midas 1.0.0

MIDAS API client.

Spec-driven HTTP client built on Martian. The OpenAPI spec bundled in resources/midas-spec/openapi.yaml is the single source of truth for endpoint definitions and parameter validation.

This is a read-only CONSUMER client. In MIDAS v2.0 all public GET endpoints are unauthenticated — use (create-anonymous-client) and skip the token entirely. A bearer token is only needed for uploads (POST), which require CEC-issued utility credentials; the authenticated flow below exists for utility data providers and is not exercised by non-utility consumers.

Authenticated flow (utility uploads only):

1. Call (get-token username password) to obtain a 10-minute bearer token
2. Call (create-client token) to create an authenticated Martian client
3. Use the client with API functions (rin-list, rate-values, etc.)

api-url clj

body clj

(body response)

Extract the parsed body from an HTTP response.

create-anonymous-client clj

(create-anonymous-client)

(create-anonymous-client
  {:keys [url spec-path zone]
   :or {url api-url spec-path default-spec-path zone default-zone}})

Create an unauthenticated MIDAS API client (v2.0 GET endpoints only).

In v2.0 all public GET endpoints are unauthenticated, so this constructor acquires no token and sends no Authorization header. Use it for fetching rate values, RIN lists, historical data, and lookup tables. For uploads (POST — still authenticated) use create-client or create-auto-client.

Options: :url - API base URL (default: production) :spec-path - path to OpenAPI YAML on classpath (default: bundled spec) :zone - ZoneId or zone-id string for bare datetime coercion (default: America/Los_Angeles)

create-auto-client clj

(create-auto-client username password)

(create-auto-client
  username
  password
  {:keys [url spec-path zone]
   :or {url api-url spec-path default-spec-path zone default-zone}})

Create a MIDAS client that automatically refreshes its bearer token.

Acquires an initial token using the provided credentials and transparently refreshes it before any request where the token is expired or about to expire (within 30 seconds).

Options: :url - API base URL (default: production) :spec-path - path to OpenAPI YAML on classpath (default: bundled spec) :zone - ZoneId or zone-id string for bare datetime coercion (default: America/Los_Angeles)

create-client clj

(create-client token)

(create-client token
               {:keys [url spec-path zone]
                :or
                  {url api-url spec-path default-spec-path zone default-zone}})

Create an authenticated MIDAS API client from the bundled OpenAPI spec.

token can be either a raw token string or a token-info map from get-token.

Options: :url - API base URL (default: production) :spec-path - path to OpenAPI YAML on classpath (default: bundled spec) :zone - ZoneId or zone-id string used by the coercion layer to produce ZonedDateTime values for bare MIDAS datetimes (default: America/Los_Angeles, MIDAS's native zone — see the api-specs doc/datetime-and-timezone.md)

The configured zone flows through every get-* fn onto each response as :midas/zone, where midas.entities reads it during coercion.

default-spec-path clj

default-zone clj

Default timezone for MIDAS bare datetime fields.

MIDAS is the California Energy Commission's API; any bare datetime fields with no zone suffix are interpreted as local America/Los_Angeles wall-clock time. (In v2.0 most boundary fields carry explicit UTC, and the RIN-list LastUpdated carries a basic-format offset.) See https://github.com/grid-coordination/midas-api-specs/blob/main/doc/datetime-and-timezone.md

get-historical-data clj

(get-historical-data client rin startdate enddate)

Fetch archived rate data for a RIN within a date range.

Dates are ISO 8601 strings (e.g. "2023-01-01"). v2.0 supplies the RIN as a path parameter (/HistoricalData/{rate_id}) and enforces a 6-month maximum range per call — split larger ranges across multiple calls.

(The v1.0 /HistoricalList endpoint was removed in v2.0; for the full active RIN list use (get-rin-list client 0).)

get-lookup-table clj

(get-lookup-table client table-name)

Fetch a MIDAS lookup/reference table. table-name: Country, Daytype, Distribution, Enduse, Energy, Location, Ratetype, Sector, State, or Unit.

get-rate-values clj

(get-rate-values client rin query-type)

Fetch rate/price values for a specific RIN. query-type: "alldata" or "realtime".

get-rin-list clj

(get-rin-list client signal-type)

Fetch list of available RINs by signal type. signal-type: 0=All, 1=Rates, 2=GHG, 3=Flex Alert.

get-token clj

(get-token username password)

(get-token username password {:keys [url] :or {url api-url}})

Authenticate with MIDAS using HTTP Basic auth and return a bearer token.

The token is returned in the Token response header and is valid for 10 minutes. Returns the token string on success, nil on failure.

Options: :url - API base URL (default: production)

register clj

(register {:keys [fullname username password email organization]})

(register {:keys [fullname username password email organization]}
          {:keys [url] :or {url api-url}})

Register a new MIDAS API user account.

All string fields are automatically base64-encoded as required by the API. Returns the raw HTTP response. organization is optional.

Options: :url - API base URL (default: production)

routes clj

(routes client)

List all available route names for the client.

success? clj

(success? response)

True if the HTTP response has a 2xx status.

token-expired? clj

(token-expired? token-info)

(token-expired? token-info buffer-seconds)

True if a token-info map is expired or will expire within buffer-seconds (default 30).

token-info clj

(token-info client)

Get the current token-info from a client (works with both client types).