Skip to documentation content
Scraping OperationsDocs
Back to website
FIEN

SDK overview

Generated source packages and one shared client contract across ten server-side ecosystems.

10 min Updated 2026-08-13Docs version 1.0
In this guide
  1. 1Understand the status
  2. 2Use one client contract
  3. 3Rely on safe defaults
  4. 4Version without surprises
In this guide
  1. 1Understand the status
  2. 2Use one client contract
  3. 3Rely on safe defaults
  4. 4Version without surprises

Generation and release status

Versioned source packages are generated from the canonical OpenAPI contract for TypeScript, Python, Go, Java, Kotlin, .NET, PHP, Ruby, Rust, and Elixir. Every package includes the same high-level run, wait, retry, cancellation, export, and signed-webhook runtime contract.

Automatic OpenAPI synchronization

OpenAPI is the source of truth. Every contract change regenerates all ten SDK source packages with one pinned generator version, records the exact specification hash, and opens an automatic review pull request on the main branch.

  1. 1
    npm run sdk:generate regenerates every package locally
  2. 2
    npm run sdk:check fails when committed packages differ from OpenAPI
  3. 3
    GENERATION.json binds each package to the API version and SHA-256 digest
  4. 4
    The public manifest exposes package and file hashes for release verification
Download OpenAPIView SDK generation manifest

Package identities and support

EcosystemDistributionNamespace or importRuntime target
TypeScript@nordicdevhouse/sdk@nordicdevhouse/sdkNode.js 22+ on the server
Pythonnordic-devhousenordic_devhousePython 3.11+
Gogithub.com/nordicdevhouse/nordicdevhouse-gonordicdevhouseTwo latest stable Go releases
Javacom.nordicdevhouse:nordicdevhouse-javacom.nordicdevhouse.sdkJava 21+
Kotlincom.nordicdevhouse:nordicdevhouse-kotlincom.nordicdevhouse.sdk.kotlinJVM / OkHttp
.NETNordicDevhouseNordicDevhouse.NET 8+
PHPnordicdevhouse/sdkNordicDevhouse\SdkPHP 8.2+
Rubynordic_devhouseNordicDevhouseMaintained Ruby releases
Rustnordic-devhousenordic_devhouseStable Rust with Tokio
Elixir:nordic_devhouseNordicDevhouseMaintained Elixir and OTP releases

One client contract

All ten packages expose the same API resource model in the conventions of their language. The generated high-level runtime hides job creation, polling, transient retries, deadlines, pagination, telemetry, and result decoding behind one deep interface; start and wait remain available when the application needs explicit durable job control.

CapabilityCross-SDK contract
Run and wait for a scrapeCreate one idempotent job, follow it to a terminal state, and return a typed result
Start without waitingReturn a stable job ID after the server accepts the job
Wait for an existing jobResume by job ID with a deadline and caller cancellation
Read current job stateReturn the same job states and timestamps in every language
List jobsUse server cursors and stream all pages without client-side offset math
Create a dataset exportReturn a typed export with an expiring download URL
Verify a webhookValidate raw bytes, reject replays, and return a typed event

Production defaults

ConcernSDK behaviour
CredentialsRead the explicit apiKey option or NORDIC_DEVHOUSE_API_KEY; never expose keys to browser code
HTTP timeout30 seconds per network request; configurable per client and per call
Job wait10 minutes overall; polling observes server retry hints and accepts cancellation
RetriesAt most 3 retries after the initial request for network failures, 408, 429, and 5xx with backoff and jitter
IdempotencyCreate calls receive one SDK-generated key that is reused across automatic retries unless the caller supplies a stable key
ObservabilityEvery result and error exposes request ID, job ID when available, attempt count, and SDK version

Shared error model

Each language has one root error family and narrows only when recovery differs: exceptions where idiomatic, errors.Is/errors.As in Go, a non-exhaustive enum in Rust, and tagged tuples in Elixir. Authentication, permission, validation, rate-limit, timeout, network, server, and webhook-signature errors retain the server code and request ID.

Error familyAutomatic retryCaller action
Authentication / permissionNoReplace credentials or change scope
ValidationNoFix the request fields
Rate limitYes, within retry budgetQueue or slow work if retries are exhausted
Network / timeout / 5xxYes, within retry budgetRetry later or surface an operational failure
Webhook signatureNoReject the event and inspect the raw body handling

Versioning contract

SDK packages use semantic versioning. SDK major version 1 targets REST API v1. New optional fields and resources may be added in minor releases; removing fields, renaming operations, or changing default retry semantics requires a new major version. Each package ships the strongest native type metadata supported by its ecosystem.

  1. 1
    One documented deprecation cycle before a breaking removal
  2. 2
    Changelog entries identify SDK version, REST version, and migration action
  3. 3
    Unknown response fields are preserved or safely ignored
  4. 4
    Recorded HTTP fixtures keep all ten implementations behaviourally aligned

Implementation acceptance criteria

An SDK is ready to publish only when the interface in these docs passes contract tests against the same mock server and recorded API fixtures.

  1. 1
    Authentication and redaction tests prevent secret leakage
  2. 2
    Retry tests cover Retry-After, jitter, cancellation, and exhausted budgets
  3. 3
    Webhook test vectors cover valid, stale, and malformed signatures; callers can deduplicate verified event IDs to prevent replayed processing
  4. 4
    Every implementation passes the same job-state and error-mapping fixtures
  5. 5
    No official SDK sends API keys from browser or client-side application code
Was this page helpful?