Driving the Web Service over HTTP
The HiNC web service exposes everything its browser client does as a REST API, so a script or an agent can build, save and run a project with no browser open. This page is what such a caller needs around its requests: where the contract is and where it is wrong, how to sign in and read a reply, and how files and projects are addressed. Editing through an object-store key, and making that edit reach the run, are Editing Objects by Key; replaying a mission is Running a Replay; coloring a run's steps by condition is Step Color Trees over HTTP. The order in which a project is assembled is Project Construction.
Contract and Sign-In
The service publishes its contract as two OpenAPI documents, both served in every environment:
- The Swagger document, opened from the Swagger UI at
/swaggerand served at/swagger/<contract version>/swagger.json— currently/swagger/v3.1/swagger.json. The UI always loads the current one, so a guessed/swagger/v1/swagger.jsonis a 404, not a missing contract. The UI and its document answer ahead of the sign-in stage and are readable without a session. - The framework document at
/openapi/v1.json. It is an ordinary routed endpoint, so while the login gate is on it needs the session cookie like any other route.
A caller given only the service's address finds the Swagger document and this page from its first
request. The application's page answers with a Link header
(RFC 8631) naming the Swagger document as
rel="service-desc" and this page as rel="service-doc". The service sends that page for GET /
and for any other GET or HEAD outside /api that no file, the Swagger UI, the documentation site or
a hub answers, as long as the last path segment has no dot (under /util/file-explorer/ it may have
one). The page's HTML <head> carries a service-doc link to this page and a help link to the
documentation site at /HiAPI-docsite/; the page is minified, so its attribute values are unquoted.
The page, the documentation site and the Swagger document are all readable without a session. The
Swagger document's description names this page and
Project Construction.
Routes and query parameters agree between the two. Request bodies do not. The framework document names every schema by its simple type name, so request types that share a name in different controllers collapse into one schema, and several routes advertise another route's body. Take body shapes from the Swagger document, which names schemas by full type name. Where only the framework document is at hand, these are the routes it gets wrong:
| Route | Shown as | Actually reads |
|---|---|---|
POST /api/mech/machine-tool/load |
{ xmlText, loadResources } |
{ rootName, relFile }, with rootName either ProjectDirectory or ResourceDir |
POST /api/Workpiece/workpiece-material/load |
{ xmlText, loadResources } |
{ rootName, relFile } |
POST /api/Workpiece/cutting-parameter/load |
{ xmlText, loadResources } |
{ rootName, relFile } |
POST /api/mech/spindle-capability/load |
{ xmlText, loadResources } |
{ xmlText, baseDirectory, relFile }; loading by path is POST /api/mech/spindle-capability/load-file with { rootName, relFile } |
POST /api/file-explorer/rename |
{ name } |
{ rootName, relativePath, newRelativePath } |
JSON property names are matched case-insensitively, so RootName and rootName are the same field,
and enumerations travel as their names. Values are not relaxed the same way: root names and geometry
or transformer kind names are compared exactly as written on this page.
Check the login gate before anything else. The shipped configuration leaves it off, so an
installed copy answers every route with no session, on its own computer only: its address is
localhost, and while the gate is off and the service's AllowedHosts names no other host, a
request addressed to any host name but localhost, 127.0.0.1 or [::1] is answered
400 Bad Request, and one from another computer that writes one of those names 403 with a
plain-text line saying what to set, so widening the address alone does not let a script on another
computer in.
A deployment can turn the gate on, which lifts both, the host names unless it sets AllowedHosts;
while the gate is on every route outside /api/auth answers 401 with an empty body until the caller has
signed in — which reads exactly like a service that is not running. GET /api/auth/status is always
anonymous and reports whether the gate is enabled, whether this caller is signed in, and the service
version. Sign in with POST /api/auth/login and the JSON body { username, password }. A good pair
answers { authenticated: true, … } and sets a cookie every later request must carry, so use an HTTP
client with a cookie jar; a wrong pair answers 401 with the code InvalidCredentials. With the gate
off, the login answers success without reading the body, so a script may sign in unconditionally. A
script in a browser page works only from a page the service served itself: the service sends no CORS
headers, so no other page may read its answers, and while the gate is off it answers 403 to another
page's requests — one on another port of the same computer included. A script outside a browser
sends neither Origin nor Sec-Fetch-Site and is not affected. Some routes answer with data but
are POSTs, because they also register the object they return for later editing, write files as they
serialize, or open a path you name: the Tool House holder and beam reads (CylindroidHolder/Get,
FreeformHolder/Get, Cutter/{id}/inner-beam, Cutter/{id}/upper-beam), ObjectManagement/GetXml,
mech/machine-tool/xml, NcProgram/file-lines and StlFile/GetFileInfo. A GET to one of them
answers 404, as a route that does not exist does (Reading a Reply). A few GETs still fill in a controller
parameter table's missing default as they read it, which a later project save writes out.
Then read GET /api/Project/status once. It reports whether a project is open, its path, and the
admin and project folders on the server, absolute when the admin folder is configured as one. Confirm the admin folder is the tree meant to be
written into before writing anything: a service started from a different configuration comes up just
as healthy, pointed at a different tree.
Reading a Reply
Routes take their input in one of three shapes, and the Swagger document says which: a JSON object
body such as { rootName, relFile }; query parameters, which is how most key-based edit routes take
both their key and their values — a route that takes a list, such as
POST /api/Cylindroid/UpdateAllPairs, takes the key as a query parameter and the list as a JSON body
(see Editing Objects by Key); or a bare JSON
value as the whole body — PUT /api/Workpiece/init-resolution takes the number itself, 0.25, not an
object.
An HTTP 200 does not by itself mean a request did what it asked. Many routes keep the convention their
browser client relies on: a refusal that is not a malformed request comes back as 200 with
success: false and a message, and some partial successes come back as success: true with
warnings in messages. For example:
POST /api/mech/machine-tool/loadnaming a file that does not exist, or called with no project open, answers 200 withsuccess: false; so do the workpiece-material and cutting-parameter loaders for a missing file or one that does not deserialize;POST /api/Mission/list-command/entrieswith a command kind the catalog does not know answers 200 withsuccess: false;POST /api/Workpiece/workpiece-material/loadand the cutter'sflute-material/load,shank-material/loadandcoating-layers/{index}/material/loadinstall a material whose thermal constants are implausible as written, or not given — an element the file lacks takes no default, and the thermal model is skipped for the tool (for every tool when it is the workpiece material) — and carry the warning inmessages(Material-ThermalConstants--NotGiven,Material-ThermalConstants--NotFinitePositive,Material-ThermalConstants--OutOfRange; the flute and coating-layer loads alsoMaterial-WearCurves--NotGiven, a cutter material whose file lacks itsTemperatureVsHardnessCurveorTemperatureVsWearCoefficientCurve: installed, named, the native thermal model does not run for the tool).
Malformed requests answer 400 — an unknown root name, a path that leaves its root, an empty required
field — and so do some refusals of a well-formed request, which then change nothing.
POST /api/StlFile/UpdateSource whose file cannot be loaded — not there, not readable, or not an STL
the reader can parse — answers 400 with success: false, the code StlFileLoadFailed and its args
(file, reason) beside the English message, and sourceFile, the file the StlFile still
references: the StlFile keeps that file and its mesh, which GetInfo goes on reporting.
StlFile/UpdateSourceFile and StlFile/Reload answer the same. args.reason is the reader's
English with the cause it wraps: an ASCII file is refused at the first line that is not what the
format expects and when it ends before endsolid, even between two facets, and the reason names
the line — Stl Loading failed. Line 6: a vertex needs three numbers, read 'vertex 0 1'.,
Stl Loading failed. The file ends at line 8, before 'endsolid'. — while a binary file cut short
reads Stl Loading failed. Unable to read beyond the end of the stream. A binary file is read for
as many triangles as its header counts, so one whose header counts none loads as an empty mesh, as
does an ASCII file with no facet between solid and endsolid: compare triangleCount with the
file, not only loaded — an empty mesh answers loaded: true,
triangleCount: 0 and box: null.
An object-store key that does not exist answers 404, and a key holding the wrong kind of object
answers 409. Most routes that create an object in the store answer with its key as a bare string —
plain text, unless the request's Accept header asks for JSON, which yields a quoted JSON string; a
few, such as POST /api/Cutter/{id}/upper-beam/create, answer a JSON object carrying the key.
A route that does not exist answers 404. A GET or HEAD to a path under /api that no route
serves — a misspelt route, or one that takes only POST — answers 404 with an
application/problem+json body whose detail names the method, the path, the Swagger document and
this page; any other method answers 405. No route answers HEAD, so a HEAD answers 404 even where a GET would answer. A path
outside /api belongs to the application's page, so a GET that leaves out the
/api prefix answers 200 with HTML (text/html). Check that the reply's Content-Type is the one
the route answers with — application/json for a JSON reply, text/plain for a bare key, a file
type for a download — before reading anything from it.
A reliable caller therefore checks the status code, then success, then messages, and follows each
write with the matching read before building on it: GET /api/mech/machine-tool after a chain load,
GET /api/StlFile/GetInfo (loaded, triangleCount) after pointing an STL at a file,
GET /api/Workpiece/Status once the workpiece is set up.
One Service, One Project
A service instance holds exactly one open project and one object store, shared by every browser and every script connected to it. What to read before driving an instance other people may be using, and which edits, plays and calls are refused while a run is live or the project is changing, is on One Service, One Project.
Files and Named Roots
Every file path the API takes is relative to one of three named roots, passed by name:
| Root name | Resolves to |
|---|---|
AdminDirectory |
the service's working area; the project paths given to /api/Project/* are relative to it |
ProjectDirectory |
the folder holding the open project file — unavailable, and refused with 400, while no project is open; a request that states the folder it expects is refused with 412 once the root names another (below) |
ResourceDir |
the shipped library, the Resource folder under the admin area |
GET /api/file-explorer/roots lists the roots available at the moment. A path that leaves its root,
or names a git directory (.git) or anything in one, is refused with 400, as is every path under a
Project root that lies in one. The paths a mission command stores take no root name: a Program File's program
and a Post-Execution template are relative to the project folder, the one ProjectDirectory names,
and an absolute template is used as it is.
Files reach the server through the routes under /api/file-explorer:
| Route | Arguments |
|---|---|
POST upload |
query rootName and relativePath; the file as the multipart form field file. Missing parent folders are created and an existing file is overwritten. |
POST write-text |
body { rootName, relativePath, content }; written as UTF-8 without a byte-order mark, parent folders created |
POST create-directory |
body { rootName, relativePath }; a no-op when the folder exists |
GET list, GET download, DELETE delete |
query rootName and relativePath; delete removes a folder recursively |
A refusal of a root, a path, a name or a file on these routes carries, beside its English
message, a code and the args it names — FileExplorerRootUnavailable (root),
FileExplorerPathNotFound (path), FileExplorerPathTaken (path), FileExplorerPathOutsideRoot,
FileExplorerCopyNamesTaken, FileExplorerInvalidName (name, chars) for a name the server's
file system cannot hold, FileExplorerFileReadOnly, FileExplorerAccessDenied and
FileExplorerFileInUse for a write-text the file itself refuses (read-only, the write denied,
another program holding it open) — so a script branches on the code, never on the English sentence; the statuses and the sites, and the
codes write-lines answers, are listed under
File Explorer Refusals.
There is no cross-root copy: copy duplicates beside the source and rename refuses to move between
roots. Because ProjectDirectory exists only once a project is open, inputs staged before the
project is created go to AdminDirectory, under the folder the project file will sit in —
<project folder>/NC/…, <project folder>/Geom/… — and are addressed through ProjectDirectory
afterwards.
What a loader does with a file depends on where it came from:
- Pre-prepared resources — machine-tool chain, spindle capability (
load-file), workpiece material, cutting parameters, cutter material — are loaded by{ rootName, relFile }. A file already inside the project is referenced where it is. A file picked underResourceDiris written into the project at the same sub-path, for exampleWorkpieceMaterial/<name>, and referenced there, so the saved project never points into the shared library; a file picked elsewhere underAdminDirectoryis written into the project root under its own name. Uploading the file into the project first and loading it fromProjectDirectorycomes to the same thing, and it is the form to use whenever the copy is not there: after a pick from the library, list the project's folder (GET /api/file-explorer/list?rootName=ProjectDirectory&relativePath=WorkpieceMaterial, and so on) and check the file landed — an instance whose loaders do not copy stores a reference that resolves to nothing, and the next save or close fails withCould not find file. The machine-tool loader accepts onlyProjectDirectoryandResourceDir, and a chain picked from the library comes with its side files. - An STL set with
POST /api/StlFile/UpdateSourceand{ stlFileKey, rootName, relFile }is recorded project-relative; one picked outside the project is recorded asGeom/<file name>, and its mesh is written there at the latest on the next save — but only when no file already sits at that path: an existingGeom/<file name>is kept and the reference then names it. Give meshes from different folders distinct names, or upload them into the project first. - NC programs are recorded as the plain path a mission command names. Nothing copies them: upload them.
Holding a Request to the Project Folder
ProjectDirectory is resolved as each request arrives, to the folder of whatever project is open
then. Every route that takes a rootName takes an optional query parameter, ifProjectDirectory,
the folder the caller takes that root to name; once another browser or script has loaded or made a
project in another folder, or saved the open one into another folder, such a request is answered 412
ProjectDirectoryMoved and does nothing. The value, the routes, the answer and what the browser
client does on it are on
Holding a Request to the Open Project.
Holding a Request to the Project Generation
An edit route addresses an object of the open project — a tool by its id, a mission command by its
index path, an object-store key — and acts on the object of that id, path or key in whatever project
is open when it is handled. The web service's own edit routes take an optional request header,
If-Project-Generation, the projectGeneration the caller last read; once another browser or script
has made, loaded, reloaded or closed a project, such a request is answered 412
ProjectGenerationMoved and does nothing, and a request without the header is served as before. The
project-file routes, the run controls, /api/Index and the engine's /api/SessionShell,
/api/LocalProjectService and /api/Setup, some of which write the project, take no such header.
Which routes, the answers, the wait
while a project change runs and what a script does on a refusal are on
Holding a Request to the Open Project.
Project Lifecycle
The project routes work on the one open project, addressed by a path relative to AdminDirectory:
| Route | Body | Effect |
|---|---|---|
GET /api/Project/status |
— | hasProject, projectPath, the admin and project folders (adminDirectory, projectDirectory), and projectGeneration, the order of project changes, which the status hub and the successful New, Load, Reload, Save As and Close replies carry too: New, Load, Reload and Close move it, a Save As does not; a request states it back in If-Project-Generation (above). hasProject, projectPath and projectDirectory come from one read of the project's path and agree; the generation is read apart, so a read while a New or a Load installs its project can carry the new path with the generation before it |
POST /api/Project/new |
{ relativePath } |
creates the folder if needed, writes the new project file at once and opens it; refused with 400 when a file already exists at that path |
POST /api/Project/load |
{ relativePath } |
opens a project; the reply's messages lists load-time holes, such as a missing STL, a referenced side file that cannot be read (XmlSource-Read--Failed) or an older project's unreadable script file (ScriptFile-Read--Failed), none of which fails the load; a project file that itself cannot be read — missing, locked, malformed — is refused with 400, the message naming the file under its root, and no project is open afterwards (the open project is released before the file is read; the status hub reports it) |
POST /api/Project/reload |
— | re-reads the open project from its file, with the same messages; a file deleted, locked or damaged since is refused with 400 and no project is open afterwards: the in-memory project is released before the file is read |
POST /api/Project/save, close |
— | act on the open project |
POST /api/Project/saveas |
{ relativePath } |
writes to a new path, which becomes the open project; a file already there is overwritten without a prompt. A path that moved — on Windows a respelling in letter case too — is broadcast at once on the status hub (/executionStatusHub, ExecutionStatusUpdated; Program and Hosting); one back to the open path is not. The reply's projectGeneration, the order of project replacements, which the hub also carries, is normally unchanged — a Save As keeps the project; a newer one means another client replaced it meanwhile |
save, reload, close and saveas answer 400 when no project is open; new, load and saveas
answer 400 for a path that names a git directory (.git). The six project-file
operations take turns: one requested while another is running is refused with 409 rather than queued.
A New, Load, Reload or Close also waits for the requests held to the project generation that are
running, and is refused with 409 the same way when one of them is still running 10 s on. None of the
project routes takes If-Project-Generation: each acts on the project open when it arrives.
A new project is not empty. It carries a fixture in its default shape with an empty solid on its
geometry anchor, a workpiece with no geometry, an empty tool house and no machine chain, and a mission seeded
with eight root entries: Machining Resolution, Machining Motion Resolution, Collision Detection, Pause
on Failure, Physics, two Program File entries naming the placeholders NC/NC-File-Name-1.nc and
NC/NC-File-Name-2.nc, and a Post-Execution. The placeholder programs do not exist, and each one left
enabled raises the error RunNcFile--NotFound on every play and is skipped; the play goes on. An entry added through
POST /api/Mission/list-command/entries without an insertIndex lands at the end, after the seeded
Post-Execution. A Post-Execution writes only what has played above it, so nothing a program added
there plays reaches its outputs, and when nothing above it played either, its writers end on
StepFile-Write--NoFile and ShotFile-Write--NoFile (for the outputs switched on) instead of
finishing. Add a program with "insertIndex" set to the Post-Execution's current index — 5 once
the two placeholders are deleted — or move the Post-Execution to the end afterwards with
POST /api/Mission/list-command/entries/{path}/move and
{"direction": "to", "targetIndex": <last index>}. Edit the seeded entries in place, or delete them with
DELETE /api/Mission/list-command/entries/{path}, highest index first, because the entries after a
deleted one renumber; then read the tree back with GET /api/Mission/list-command/entries.
Rebuilding at the same path is close, delete, new: POST /api/Project/close, then
DELETE /api/file-explorer/delete?rootName=AdminDirectory&relativePath=<project path>, then
POST /api/Project/new. The other files in the folder — uploaded programs and resources — are left as
they are.
Finish every build with save, reload and a read-back. Reload re-reads the file, so the settings read after it are the ones the file actually holds; a value that does not survive the round trip was never saved.
Editing Objects by Key
Geometry, transformers, cylindroid profiles and similar setup values are edited through an object-store key: create or index the object, edit through the key, and read it back. Derived keys, the equipment's anchors and branches, and the rule that each caller prefixes its keys, are on Editing Objects by Key.
Making an Edit Reach the Run
The project holds the equipment twice — the setup that is saved, and the runtime copy a run is
built from. Which routes mark the setup edited, and how setupEquipmentDirty says an install is
still waiting, are on
Editing Objects by Key.
Running a Replay
A scripted replay is reset, then start, then poll by the runId start returned. The sequence,
the guards that keep a caller off someone else's run, and why a timeout must not call stop, are
on Running a Replay.
Step Color Trees
A script or an agent colors a run's steps by condition under /api/execution/step-color-trees. Three
rules keep it from disturbing anyone else on the instance: check and preview a tree before putting it,
add a tree with If-None-Match: *, and set the color index — a project setting every connected user
sees — only when the tree must show on screen, writing the old key back afterwards while the color index is still the tree's key. The routes, the
shape of a tree, the answers and the requests in order are
Step Color Trees over HTTP.
Request Encoding
Send request bodies as UTF-8. The service decodes JSON as UTF-8, and a client that encodes the body in another code page loses every character outside that code page before the request leaves the machine — while the call still reports success. The damage shows only when the value is read back.
Windows PowerShell 5.1 is the usual case: Invoke-RestMethod with a string -Body and a content type
that carries no charset sends ISO-8859-1, so a group title written in Chinese is saved as ??.
Send bytes instead:
Invoke-RestMethod -Method Put -Uri $uri -WebSession $session `
-Body ([System.Text.Encoding]::UTF8.GetBytes($json)) `
-ContentType 'application/json; charset=utf-8'
or use an HTTP library that sends UTF-8 by default. The same holds for a program or any other text
sent through write-text: what the request body carried is what lands in the file.
See Also
- Editing Objects by Key — object-store keys, derived keys, the equipment's anchors and branches, and how an edit reaches the run
- Running a Replay — reset, start and poll on a shared instance, and what a timeout must not stop
- One Service, One Project — what to check before driving an instance others use, and what is refused while a run is live or the project is changing
- Holding a Request to the Open Project —
ifProjectDirectoryandIf-Project-Generation, which keep a request to the project folder and the project it was built on - Getting Started with HiAPI — the in-process C# route to the same engine, with no service in between
- Project Construction — the build order these routes are used in, and which controller routes the run actually reads
- Program and Hosting — the two OpenAPI documents, the request pipeline and where sign-in sits in it
- Login and Authentication — the gate's defaults, the cookie's lifetime and the three auth routes
- File Explorer Page — the page these file routes serve
- File Explorer Source Code — the complete file-route table
- File Explorer Refusals — the codes and
argsthe file routes refuse with, to branch on instead of the English - Step Color Trees over HTTP — coloring a run's steps by condition: the color tree routes, the shape of a tree, the answers and the shared color index