Skip to content

Netzo SDK

The Netzo SDK is a JavaScript client library to make it easy to interact with APIs programatically. The SDK is written in TypeScript (types included) and can be used for both

  • backend development in Deno and Node.js
  • frontend development in the browser (e.g. angular, vue, react)

The SDK makes it even easier to interact with existing, pre-configured Services in the Workspace (via theservice client) or with custom ones (via the fetch client).

ts
const netzo = Netzo({ apiKey: API_KEY })

Modules

The following table gives an overview of the currently supported modules:

ModuleDescription
fetchClient for HTTP APIs, resource or service
serviceClient for pre-configured Services in Workspace

Refer to their respective documentation pages for more information of the above modules.

Services Client (recommended)

The service client allows interacting with existing, pre-configured Services and Service Requests. Netzo will asynchronously fetch its configuration and use it to instantiate a client.

1. Import the library

You can import the latest version of the library directly as follows from mod.ts, the module entry point:

js
import { Netzo } from 'https://deno.land/x/netzo/mod.ts'

or import a specific version directly, for example v0.1.0, as follows:

js
import { Netzo } from 'https://deno.land/x/[email protected]/mod.ts'

2. Instantiate the SDK

To create an instance of the SDK pass in a valid API_KEY, for example:

js
const netzo = Netzo({ apiKey: API_KEY })

The netzo SDK instance will automatically handle authentication for the Service and its Requests in the workspace. Its access level is scoped to the workspace that owns the API key.

Be sure to keep your API keys secret by using environment variables.

3. Instantiate a Service

Pass-in the ID of the Service to the netzo.service() method:

ts
const { client, requests, item, save } = await netzo.service(SERVICE_ID)

This will automatically fetch the latest serviceOptions from the Netzo API and create a client for it. Note the use of await is required.

The save utility can be used to save changes to item in the database.

3.2 Create a custom service from scratch

Manually pass-in the the options to the netzo.service() method:

ts
const { client, requests, item, save } = netzo.service(serviceOptions)

The save utility can be used to create and then save changes to item in the database.

4. Instantiate a Service Request

Once you've instantiate an existing or new Service, you can access existing Service Requests or create new ones with requests.

ts
// select existing by ID
const request = await service.requests[SERVICE_REQUEST_ID]

// create new by passing-in request options
const newRequest = service.requests(requestOptions)
await newRequest.save() // [optional] save new (to workspace)

Pass-in the ID of the Service Request and call the .invoke() method on it.

ts
const users = await client.requests('SERVICE_REQUEST_ID').invoke()
Service Request Options

Note that baseURL defaults to "/" and headers are optional. Options passed to the netzo.service() method will be taken as defaults but can be overriden per request.

ohmyfetch is used internally for data fetching. Thus, every option available for ohmyfetch is usable as well. The following options are available:

ts
interface ServiceRequestOptions {}

4.2 Create a custom service request from scratch

Manually use the path and/or bracket syntax and call the desired HTTP method on it:

ts
const users = await client.users.get()

Full Example

The following example applies the previous steps to instantiate the Netzo SDK, create a Service instance and invoke a request with custom parameters.

js
import { Netzo } from 'https://deno.land/x/netzo/mod.ts'

const netzo = Netzo({ apiKey: Deno.env.get('API_KEY') })
const client = await netzo.service('SERVICE_ID')
// GET <baseURL>/users
const data = await client.users.get()
// PATCH <baseURL>/users/8
const data = await client.users(8).patch({ name: 'Miguel' })

Asynchronous operations

Note that you might need wrapping your code in an async function and await calls to asynchronous SDK methods. Deno supports top-level await so this is not needed.

Error handling

Note that the SDK will throw an error if the request fails. To handle potential errors, wrap your code in a try block, and pass any error handling code in the catch block.

Example: Handling potential errors
ts
try {
  // async code might fail, throwing an error
  await client.users.get()
}
catch (error) {
  // (optional) code to handle error
}
finally {
  // (optional) code to run after try/catch
}

Type Definitions

Refer to types.ts for the type definitions of this module.

Netzo SDK has loaded