Ruby

The Ruby SDK for the Neon API, generated from the same spec as the other nine.

Get the source

gh repo clone OctriDev/neon-ruby-showcase-sdk

The repository's README lists the toolchain and build commands for Ruby. Open it on GitHub.

Quickstart

require "octridev_neon"

config = OctridevNeon::ClientConfig.new
# Optional: replaces the default server and any server an operation declares.
config.base_url = "https://console.neon.tech/api/v2"
auth = OctridevNeon::ClientAuthConfig.new
auth.bearer_auth = ENV.fetch("API_TOKEN")
config.auth = auth
client = OctridevNeon::Neon.new(config)
result = client.branch.get_masking_rules(project_id: "a", branch_id: "a")
p result

Authentication

Keep credentials outside source control. The quickstart reads them from the environment and the client applies them to every request.

Scheme	ClientAuthConfig field	Sent as
BearerAuth	`bearer_auth`	`Authorization: Bearer …`
CookieAuth	`cookie_auth`	`zenith` in cookie
TokenCookieAuth	`token_cookie_auth`	`keycloak_token` in cookie

Client behavior

Base URL: https://console.neon.tech/api/v2.
Transport: Net::HTTP.
Timeout: 30,000 ms per attempt.
Retries: up to 3 attempts for status codes 408, 425, 429, 500, 502, 503, 504, with 500-8,000 ms backoff.
Idempotency: enabled for POST, PATCH using Idempotency-Key.
Error telemetry: off. This build has no reporting endpoint and sends no error reports.

High-level operation methods return the typed response body directly. The low-level request layer returns an SdkResponse<T> envelope containing data, status, headers, request ID, latency, and attempt count.

Errors

All failure paths use a small, predictable hierarchy:

Error	Meaning
`SdkValidationError`	A request argument failed an OpenAPI constraint before network I/O.
`SdkHttpError`	The server returned a non-2xx response.
`SdkApiError`	A 2xx response whose error envelope, when the API declares one, reports a failed call. It carries the envelope's error code.
`SdkResponseDecodeError`	A 2xx response body or stream event did not decode into its declared type. It keeps the raw body.
`SdkNetworkError`	DNS, connection, TLS, or socket failure.
`SdkTimeoutError`	The configured per-attempt timeout elapsed.

HTTP errors expose status_code, the response body and headers, plus request_id when the server supplies one. Preserve the request ID in support logs; it is the fastest way to correlate a failed SDK call with server-side traces.

Common statuses are reported as a subclass of SdkHttpError, so a handler can catch only the one it handles: SdkBadRequestError (400), SdkUnauthorizedError (401), SdkPermissionDeniedError (403), SdkNotFoundError (404), SdkConflictError (409), SdkUnprocessableEntityError (422), SdkRateLimitError (429), SdkInternalServerError (any 5xx). Any other status is reported as SdkHttpError itself.

When the API declares a model for an error response, the SDK decodes the body into it as error.data; narrow it with is_a?. It is empty when the status declares no model or the body does not fit one. The raw body stays on the error either way, and error.decode_body(ErrorModel) decodes it into any ErrorModel by hand.