API Design: How to ensure commands are called in a specific sequence

we're designing an API for our handheld sensor that we manufacture so that our customers can integrate it onto their robots.

The functionality on the sensor requires a user to go through a sequence of steps to achieve a final result. When a user is using our device as a handheld, we're able to force the user to follow this sequence because our GUI walks them through each step. However, with our API it's a little more difficult since the integrators can make calls in no particular order. Currently we're relying on documentation to make sure the API calls are made sequentially.

But, my question to you is: can this be done via the API?

For example, I tried the following but I ended up backing out of this approach because I felt it was becoming too opinionated and, in the end, not enforceable.

The user makes the following request to our sensor's API

{
	"command": "do_step_one"
}

When the sensor responds that it's "done", it suggests a next step and the option to cancel, like so:

{
	"respondingToCommand": "do_step_one",
	"date": "2023-04-03T19:23:23.000000",
	"message": "Successfully completed step one",
	"nextStep": [
     {
       "name": "Continue to step two",
	   "command": "do_step_two"
	 },
     {
       "name": "Cancel",
	   "command": "cancel_sequential_process"
	 },
    ],
	"status": "done"
}

For this brief answer I'll ignore the "tough love" school of thought about API design, in which users who disregard the documented way of doing things get what they get. Consider a big customer who finds a weird way to make something work, but your next internal fix breaks their workflow – "why should we fix our code, you're the ones who broke it!"

You can enforce a certain order of requests by requiring resources that are only available from previous responses. As a generic example, your steps might be:

1. Login, which returns an authentication token
2. Start a hardware session using the auth token, which returns a session id
3. List available sensors using the session id, which returns a list of sensor ids
4. Power on sensor using the session id and a sensor id, which returns a session-specific sensor handle
5. Poll sensor status using the sensor handle
6. Close the session using the session id

Each step builds on previous steps. The user still has freedom – for instance, it might make sense for the sensor ids to be persistent between sessions, so maybe they can go straight to step 4 without step 3, and just re-use a sensor id that they have stored from a previous session.

Given a particular goal, the API user should be able to determine the previous steps that they require, and a good way of doing that is by having associated resources – even if they're just ids proving that they've done prerequisite tasks.

The best APIs lead you down a garden path, rather than send you into a dark wood with bear-traps hidden about the place.