EndPointBlank.Management (end_point_blank_elixir v0.12.0)

Copy Markdown View Source

A client for the EndPointBlank organization management API (/api/v1, sc-1504): your organization, API packages, clients and what they hold, applications, environments, runtime credentials and managed clients.

It is separate from the runtime SDK on purpose. It reads none of EndPointBlank.configure/1's settings and sends none of them: the only credential it sends is the management key you give it, as Authorization: Bearer epb_mk_..., and only to :base_url. Create a management key in the portal; keys cannot be created through the API.

mgmt = EndPointBlank.Management.new(key: System.fetch_env!("EPB_MGMT_KEY"))

{:ok, organization} = EndPointBlank.Management.Organization.get(mgmt)

One module per resource, each taking this client first:

Results

Every call answers {:ok, result} or {:error, %EndPointBlank.Management.Error{}} and never raises. result is the API's data, decoded JSON with string keys. A list call answers one EndPointBlank.Management.Page; the matching stream function pages through all of them lazily and raises the error instead, since a stream cannot answer a tuple.

Retries and idempotency

Every POST sends an Idempotency-Key: a random UUID, or the one passed as idempotency_key:. A retry sends the same key, so the API runs the request once. The client retries, up to :max_retries times:

  • a 429 rate_limited answer, after its Retry-After seconds (any method);
  • a 409 idempotency_request_in_progress answer (a POST);
  • a 5xx answer or a request that got no answer, for GET, DELETE and POST only. A PATCH is never retried for these.

409 idempotency_replay_unavailable is never retried: the first request succeeded and its answer held a credential secret shown once. Get or list the credential instead.

Managed clients

for_managed_client/2 gives a client that acts on one of your unclaimed managed clients' applications, environments and credentials, under /api/v1/clients/:client_id/....

Summary

Types

result(value)

What every management call answers.

t()

Functions

base_url(management)

The base URL every call goes to.

for_managed_client(client, client_id)

A client that acts on your managed client client_id's organization: the Applications, ApplicationEnvironments, Environments and Credentials modules then call /api/v1/clients/:client_id/.... Every other module refuses it with "not_available_for_managed_client", without a request.

new(opts)

Builds a management client. Raises ArgumentError for a bad option; the message never repeats the key.

Types

result(value)

@type result(value) :: {:ok, value} | {:error, EndPointBlank.Management.Error.t()}

What every management call answers.

t()

@type t() :: %EndPointBlank.Management{
  base_url: String.t(),
  key: String.t(),
  managed_client_id: String.t() | nil,
  max_retries: non_neg_integer(),
  max_retry_wait_ms: non_neg_integer(),
  receive_timeout: pos_integer(),
  req_options: keyword(),
  sleep: (non_neg_integer() -> any())
}

Functions

base_url(management)

@spec base_url(t()) :: String.t()

The base URL every call goes to.

for_managed_client(client, client_id)

@spec for_managed_client(t(), String.t()) :: t()

A client that acts on your managed client client_id's organization: the Applications, ApplicationEnvironments, Environments and Credentials modules then call /api/v1/clients/:client_id/.... Every other module refuses it with "not_available_for_managed_client", without a request.

The API answers 404 once the customer has claimed the client.

new(opts)

@spec new(keyword()) :: t()

Builds a management client. Raises ArgumentError for a bad option; the message never repeats the key.

Options:

  • :key (required) -- a management API key, epb_mk_....
  • :base_url -- defaults to https://app.endpointblank.com.
  • :max_retries -- how many times one call is retried (see the module docs). Defaults to 2; 0 turns retries off.
  • :max_retry_wait_ms -- the longest Retry-After the client waits out (default 60 000). A longer one is answered as the rate_limited error, with :retry_after set.
  • :receive_timeout -- per attempt, in milliseconds (default 15 000).
  • :sleep -- the function that waits between retries, given milliseconds. Defaults to Process.sleep/1; tests pass their own.
  • :req_options -- extra Req options for every request (for example plug: in tests). Options this client sets itself win, and :auth is dropped: the only credential sent is the management key.