Node, Python, Go, or Ruby: which Norbelys SDK should you use?
A practical decision guide to the four official Norbelys SDKs: which fits an edge Worker, a data script, a high-throughput backend, or a Rails app.
By Gabriel Lara, Developer Relations, Norbelys
Founder-reviewed ·How we research and correct articles
Norbelys ships four official SDKs — @norbelys/sdk on npm, norbelys on
PyPI, plus Go and Ruby packages — all generated from
the same OpenAPI spec that
describes the whole REST API. That means there’s no
“better-maintained” one and no risk of picking a second-class client — the
83 operations behind each are identical. The real question is narrower: which
runtime does the code calling Norbelys already live in?
This isn’t a benchmark or a popularity contest. It’s a decision guide, sorted by the situation you’re actually in.
Start from where the code already runs
The single biggest mistake in choosing an SDK is treating it as a language preference. It isn’t — it’s a deployment-target question. If you write Go day to day but the integration lives inside a Cloudflare Worker, the Node SDK is still the right pick, because that’s the only runtime a Worker supports. Match the SDK to where the calling code has to execute, not to what you’d reach for on a greenfield project.
| Use case | Best fit | Why |
|---|---|---|
| Edge Worker / serverless function | Node/TypeScript (@norbelys/sdk) | Runs natively on Workers, Deno, and Node — no separate runtime to provision, and types match your Worker's own TypeScript. |
| Data-science / ops script | Python (norbelys) | Fits directly into a notebook, a pandas pipeline, or a cron job without leaving the Python ecosystem your data tooling already lives in. |
| High-throughput backend service | Go | Compiled, low-overhead, and a natural fit for a service that calls the API at volume alongside other Go microservices. |
| Rails / Ruby app | Ruby | Idiomatic in a Rails codebase — matches the conventions (snake_case, exception-based error handling) your app already uses everywhere else. |
Node / TypeScript — when the caller is already JavaScript
@norbelys/sdk is the right default any time the calling code is already a
JS/TS runtime: a React or React Router app calling out from a server
component, a Next.js API route, a Cloudflare Worker, or a plain Node
service. Its biggest practical advantage isn’t the language itself — it’s
that it runs anywhere V8 does, so the same client works in an edge Worker
and a long-running Node process without a rewrite.
Reach for it when:
- Your integration lives inside a Worker or other edge runtime.
- You want request/response types to match the TypeScript types already in your frontend or backend.
- You’re prototyping quickly and want the shortest path from
npm installto a working call — see the Node quickstart.
Python — when the work is data, not a service
Python earns its place any time the job is analysis, a scheduled batch, or a one-off script rather than a long-running service handling requests. Pulling a segment of people into a notebook, backfilling a field across your contact list, or scripting a nightly export into a warehouse are all Python-shaped jobs — the ecosystem around data work (pandas, Jupyter, cron) is already there.
Reach for it when:
- The consuming code is a script, notebook, or scheduled job, not a request-serving app.
- You’re already using Python for the surrounding data pipeline and don’t want a second language in the loop.
- See the Python quickstart to get
from
pip installto a first call.
Go — when throughput and predictable latency matter
If you’re building a backend service that calls Norbelys at meaningful volume — syncing large audiences, running verification in bulk, or acting as a middle-tier between your product and Norbelys — Go’s low per-request overhead and predictable memory behavior make it a natural fit, especially if the rest of your backend is already Go. There’s no special affordance Norbelys gives Go callers beyond the SDK itself; the reason to pick it is the same reason you’d pick Go for any high-throughput service: compiled, concurrent by default, and a smaller resource footprint per request than an interpreted runtime under sustained load.
Reach for it when:
- You’re calling the API from an existing Go service and want a client that matches your codebase’s conventions.
- Throughput and tail latency matter more than developer iteration speed.
- Concurrency (goroutines fanning out list-and-process work) is central to how the integration is structured.
Ruby — when you’re already in Rails
If your product is a Rails app, the Ruby SDK is the obvious choice for the same reason the Node SDK is obvious for a JS app: it reads like the rest of your code. Idiomatic Ruby error handling, naming conventions, and the kind of “it just feels like a gem you’d expect to exist” ergonomics matter more here than in a from-scratch service, because a Rails app already has strong opinions about how external calls should look.
Reach for it when:
- You’re integrating Norbelys into an existing Rails (or general Ruby) application.
- You want the client to match the conventions — exceptions, snake_case, ActiveModel-adjacent patterns — the rest of your app already follows.
When none of the SDKs is the right call
Not every integration needs an SDK. A single curl-able webhook receiver, a quick smoke test, or a language Norbelys doesn’t ship an SDK for are all fine reasons to call the REST API directly with Bearer auth — the SDKs are a convenience layer over that same API, not a requirement to use it. If you’re driving Norbelys from an AI agent rather than application code, the MCP server or the CLI are usually a better fit than embedding an SDK at all.
Frequently asked questions
Do the SDKs differ in which API operations they support?
No. All four are generated from the same OpenAPI spec, so the same 83 operations are available in every SDK — there's no language where the client trails the API.
Can I switch SDKs later without changing my data model?
Yes. The underlying resources and Schema.org-mapped fields are identical across languages; only the calling conventions differ, so migrating an integration to a different language doesn't change how you model people, senders, or programs.
Is there a performance difference between the SDKs themselves?
Any difference comes from the runtime, not the SDK's own overhead — a compiled Go client will generally have lower per-call overhead than an interpreted Python one, but for typical integration volumes this rarely matters more than picking the SDK that fits your existing stack.
What if I need a language none of the four SDKs cover?
Call the REST API directly. It's plain HTTP with Bearer auth and JSON bodies, documented by the same OpenAPI spec the SDKs are generated from, so any HTTP client in any language can drive it.