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.com → Swagger
A tool like swagger-codegen can be used to generate ready-to-use REST API client code in a variety of programming languages.
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.
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.
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.
