1. Home
  2. Knowledge Base
  3. 4D Scale API
  4. 4D Scale APIs — Overview

4D Scale APIs — Overview

Purpose of APIs

The purpose of the 4D Scale API is to provide a programmatic way of managing 4D Scale accounts, devices, and processes.

The API requires an API key which can be obtained for any active Sellercloud team, or by creating a standalone account for 4D Scale.

4D Scale entities include accounts, devices, receivers, and snapshots.

Accounts allow integrators to receive access to the API and manage the rest of the entities using an API key.

Devices are representations of actual 4D Scale units which continuously send information (such as measurements) to the cloud. Accessible via a URL such as https://r.4dscale.com/d/<serial-number>

  • Each device has a unique serial number of the format XXXXXXXX where # is a hex digit A..F or 0..9, e.g. 7F3ABA34

Receivers are applications which connect to the cloud and listen for real-time updates from devices.

  • Receivers are essentially SignalR API clients which subscribe to real-time updates for a particular device. REST API clients are not considered receivers.
  • Each receiver should have a unique, persistent fingerprint ID that the cloud can recognize over time.
  • For example, a GUID stored in localStorage or in a file in the User Profile folder is a way option to ensure “persistent uniqueness” over time.

Snapshots are 4D Scale measurements saved at a given point in time. Accessible via a public URL such as https://s.4dscale.com/<snapshot-id>

4D Scale processes include creating a standalone account or logging in with Sellercloud team credentials; adding a device to an account — or removing one; or controlling a device.

Device actions include:

  • Initiating the tare or calibration processes
  • Obtaining the latest measurements recorded in the cloud
  • Obtaining information about receivers which have subscribed to a particular device
  • Configuring preferences for a device such as units of measurement.
  • Power cycling or shutting down a device remotely
  • Resetting preferences for a device such as units of measurement, calibration details, or the team (account) that the device is associated with.

Available APIs

4D Scale offers two ways of interacting with entities or managing processes:

REST API

REST API via JSON is arguably the most common way to manage resources online.

The API is hosted at the central api.4dscale.com domain. The automatically generated Swagger documentation and “playground” can be accessed at /swagger.
https://api.4dscale.comSwagger
A tool like swagger-codegen can be used to generate ready-to-use REST API client code in a variety of programming languages.

SSL/TLS is required.

Real-time API

Based on ASP.NET Core SignalR, it enables real-time communication between devices, the cloud, and receivers. Depending on the platform, the client library determines the best way to maintain a client-server connection.

The Receiver Hub is hosted at wss://api.4dscale.com/hubs/receiver (where wss:// is the WebSockets over TLS protocol prefix).

A receiver subscribes to a device, and the cloud pushes measurements to the receiver as they become available.

The cloud can also notify the receiver whenever a device loses connection to the cloud or reconnects, improving the user experience.

Microsoft maintain SignalR API clients for platforms such as .NET, Java, and JavaScript/TypeScript.

When in comes to successful integration, the Real-time API is of higher complexity than REST API. Please keep in mind aspects like automatic reconnection (retry policy), proper lifecycle management & disposal of resources (like connections).

The Sellercloud Support team can assist .NET and JavaScript/TypeScript integrators with sample code or NuGet packages for a streamlined integrators. Contact Sellercloud Support for more information.

Certain actions (such as account creation) are only available in the REST API.

Certain platforms (such as .NET Framework or UWP/Universal Windows Platform) may not support the wss:// protocol. Changing the Hub endpoint to https:// should be sufficient to resolve this.

API Key

An API key is assigned to every standalone account that is created, or the first time Sellercloud team credentials are used to authenticate.

The API key does not change. It can be recalled by using the Accounts controller in the REST API to log into an account that already exists.

Authentication

A common practice is to include an API key with the HTTP request sent to the cloud.

In the REST API, a request must include an HTTP header named Authorization with value Bearer <api-key>.

In the Real-time API, the API key must be included in the “access token factory” function when a HubConnection is configured. Note that the Bearer …a syntax should not be observed in the Real-time API.

Requests & Responses

The body of an HTTP request or WebSocket method (where applicable) is expected in JSON format.

Similarly, when returned, the body of an HTTP or WebSocket method response is encoded in JSON format.

Measurements

When referring to measurements in the API, a Weight reading is net. The tare value has already been subtracted from the gross weight reading.

On a related note, dimension readings are preserved in a Dimensions data structure which contains X Y Z properties. These map to Length Width Height respectively.

Was this article helpful?

Next
Integrating 4D Scale REST API