DATRON next REST API & Automation

Most CNC integration projects start with an archaeology phase: finding the PMC signals on a Fanuc, buying a FOCAS or MTConnect adapter, or coaxing macro variables out over a serial port. The DATRON next control skips that phase—it ships a documented REST API as a software option, speaking plain HTTP/HTTPS with JSON responses, complete with a machine-readable OpenAPI (OAS3) specification you can generate a client from. That puts a Datron in the same integration category as any modern web service: a monitoring dashboard, a robot cell controller, or an MES connector talks to the machine the same way it talks to everything else in the stack. This page covers the API as documented in DATRON's REST API Basic/Automation software manual (from version 2.13.1)—the variants, setup, the built-in APIviewer, and what you can realistically build on it.

What the API Exposes

The API comes in two licensed variants (manual §1.1):

Both variants are the same technology, and DATRON states that programs written against Basic need no adaptation to upgrade to Automation—so a shop can start with a Basic-license dashboard and grow into cell control without rewriting the client. The control's command scope is extended in future software versions but remains backwards compatible (from V2.13).

Transport is ordinary HTTP on port 80 or HTTPS on port 443 over TCP/IP, formatted to REST rules, callable from a browser or from the standard HTTP libraries of any language (the manual name-checks JavaScript with AJAX/jQuery, curl, and Postman). Note one browser-relevant constraint from the manual: CORS cannot be deactivated on the machine. The endpoints the manual itself names, grouped by what they touch:

The full, current list lives on the machine itself: the APIviewer (below) shows every available query and command classified in groups, and the number of groups depends on which option you purchased. The OAS3 specification—linked from the APIviewer at /api-docs/v1/oas3.json—is the authoritative machine-readable inventory.

Setup

Per the manual's setup chapter (§2), getting from a bare machine to a working API call is four steps:

1. License the option. REST API Basic or Automation is a purchased software option requiring a DATRON next control at minimum version V2.13. An activation key file obtained from DATRON is enabled on the machine under Settings → Options → Licensing; Settings → Options → Option administration lists everything available and enabled.
2. Create an API user. Under Settings → User settings → DATRON Live, create a user with a password of at least 6 characters and assign it access rights to the required apps. At least one user with the REST API authorisation must exist, and changes only take effect at the next user login or when a bearer token is generated.
3. Put the machine on the network. The machine must be reachable over TCP/IP—either a manually allocated IP address or DHCP. The manual's own tip: if you use DHCP, reserve the address, because clients with a hard-coded IP stop working the moment the lease changes; if a fixed IP is impossible, it suggests a reverse proxy such as nginx so the machine has a stable name. A terminal device can also be connected directly with an RJ45 cable. With HTTPS enabled, HTTP requests on port 80 are automatically diverted to 443, so no explicit port is needed in the URL.
4. Handle the SSL certificate. The machine's certificate will trip a browser warning on first contact ("Extended" → accept the risk). The channel is still end-to-end encrypted, but the machine's identity is not yet verified—the manual's answer is the fingerprint: view the certificate in the browser and compare it against the fingerprint shown on the machine under Settings → User settings → DATRON Live (not case-sensitive). For production, download the certificate and add it to your list of trusted company certificates so the connection verifies cleanly; every standard HTTP library also has a flag to skip verification, which is the usual reason a first curl or Postman request fails.

The APIviewer

The control ships its own interactive API explorer, the APIviewer (§3). There are two ways in. If DATRON Live is installed—DATRON's browser front-end for viewing machine data, order information and tools from any device on the network—log in at the machine's address with the user created above and tap the "API Basic" or "API Automation" app on the Overview page (a greyed-out app means that user lacks the right or the option isn't licensed). Without DATRON Live, reach the APIviewer directly by URL—e.g. http://<IP address>/apiviewer. DATRON recommends current Firefox or Chrome.

The APIviewer page has four elements: the API specification version selector, the link to the OAS3 specification (downloadable JSON, which enables automatic client generation—the FAQ points at the Swagger editor for turning it into a client in your language of choice), the Authorize control, and the list of queries and commands in groups.

Every operation opens into the familiar try-it-out pattern (§3.2): Try it out → fill parameters → Execute. Each open function shows:

• Parameters — with an "Example Value" showing one possible transfer and a "Model" showing the exact structure;
• Response content type and the expected response code (200 = OK), with a description of the answer;
• after Execute: the equivalent curl request for UNIX systems (copy-paste into scripts), the executed request URL, the JSON response body with a download option, and the response headers.

The manual walks the MachineNumber query as the worked example, since it is PUBLIC and needs no token—its FAQ recommends exactly that query as the connectivity smoke test.

Authorisation (§3.3–3.4) is bearer-token based and independent of SSL/HTTPS—it governs what the user may call. Call CreateToken in the "User" group with the machine-side username and password; the machine signs the returned token (so third parties cannot forge it), and you submit it on subsequent calls as the Authorization header value—the keyword Bearer, a space, then the token without quotation marks. In the APIviewer, click Authorize, paste the same string, and the padlock closes. Two manual-stated gotchas: the token expires every 2 months and must be renewed, and the APIviewer's Authorize dialog does not validate the token—it just stores it for the next request, so a typo surfaces later as an authorisation error.

What You Can Build

Mapping the manual's areas onto the integration jobs shops actually have:

• Monitoring dashboard / MES feed. REST API Basic alone covers this—poll the machine-state queries (the ToolInSpindle / process-data-recording tier) over HTTPS and push into whatever dashboard or MES you already run. No adapter box, no OPC layer: any language with an HTTP client is enough, and the OAS3 spec generates the client for you.
• Cell controller / robot tending. REST API Automation is the interesting one for lights-out: a cell controller can write user-persistent variables to parameterise the next job (offsets, counts, pallet ID), then LoadProgram / ExecuteProgram—including programs sitting on a USB stick or network drive—and watch state queries to know when the cycle ends and the robot may enter. Start/pause control is exactly the handshake a tending cell needs.
• Generated programs. ExecuteLines transfers and runs complete generated SimPL programs, which opens the fully dynamic case: an upstream system composes the program per part and sends it, no operator at the pendant. See SimPL Programming for what those programs look like.
• ERP / job tracking. Machine identity plus state polling gives an honest "what is this machine doing right now" feed per serial number—the boring-but-valuable input for scheduling and job costing.

A minimal cell-controller flow, using only operations the manual names (the APIviewer on your machine shows the exact paths and payloads):

POST CreateToken          (username, password)     -> signed bearer token, valid 2 months
GET  MachineNumber        (PUBLIC, no token)       -> confirm you are talking to the right machine
GET  ToolInSpindle        (Authorization: Bearer)  -> read state before committing parts
write user-persistent variables               -> parameterise the job   [Automation]
LoadProgram / ExecuteProgram                  -> run it, incl. from a network drive   [Automation]
poll machine state until cycle complete       -> release the robot / log to ERP

The manual's own FAQ makes the accessibility point directly: no automation-technology background is required—basic web development knowledge is enough to connect the API.

Troubleshooting

The manual's FAQ chapter (§4) covers the failures a first integration actually hits:

Security Notes

The manual gives you two distinct layers and it is worth keeping them straight: transport (HTTPS and the SSL certificate) and authorisation (per-user bearer tokens)—the manual notes explicitly that authorisation has nothing to do with SSL or HTTPS; it governs what the user may call. The habits that keep both layers honest:

• Verify the certificate once, then trust it properly. Compare the browser-shown certificate against the fingerprint on the machine, then install the downloaded certificate into your trusted company certificates. "Skip verification" flags belong in a first test, not in production code.
• Design for token expiry. Tokens are signed by the machine (third parties cannot forge them) but expire every 2 months. Build renewal into the integration—otherwise it is a surprise outage at month three.
• One user per integration, minimum rights. API users are real accounts on the control with assignable app rights. Give the dashboard a Basic-rights user and only the cell controller an Automation-rights user, and remember that rights changes take effect only at next login or token generation.
• Treat credentials as credentials. The username/password pair that mints tokens can start spindles on an Automation license—store it like any other production secret, not in a script comment.

And the standing caveat from this wiki's DNC & File Transfer article applies double here: a control with a REST API is a networked endpoint, and under Automation it is one that can be told to load and run programs from a network drive. If the parts are ITAR or otherwise controlled, the programs and variables reachable through this API are technical data—scope API access the way you scope access to the drawing vault: dedicated accounts, a segmented machine LAN rather than the office network, and a record of which systems hold tokens. That is ordinary systems hygiene, not a reason to forgo the API—a documented, authenticated HTTPS interface is considerably easier to govern than the ad-hoc serial links it replaces.

See also: DATRON next Control Guide for the control this API lives on; SimPL Programming for the language behind ExecuteLines and user-persistent variables; and DNC, Drip-Feed & File Transfer for how program movement works on controls without an API.

References

• DATRON, REST API Basic/Automation — Software Manual from 2.13.1, DATRON AG.