Physical Control Commands

[Rob Booth]

Hi, I just found this group and it seems like the perfect place to get some opinions and options to an issues I've been mulling over.

I have an embedded system that is using HTTP/REST as a control scheme.  For most of my system REST fits perfectly, but I have a couple places where I'm not really sure of the right direction to go.  So here is the situation: I need the ability to shutdown the embedded system with an external call here are the thoughts I've had, unfortunately none of them scream out that they are the correct way to do this.

1. /system endpoint accepting DELETE verb to shudown the system

2. /system/shutdown accepting a POST/PUT with some message structure { "command": "reboot", "message": "system going down", "delay":"now" } kinda mimicking the unix shutdown command

3. /system/commands like #2 but adding more general commands (as I have more that just shutdown that fit this style).

4. ???

I'd really appreciate any thoughts you have.  Or if you've done something like this how did you deal with it?

Thanks,

Rob

[Robert Gacki]

Hi,

you are mixing HTTP method verbs with your functional requirements too much. If you have one system (as a resource), lets talk to it on /system. Your proposals state, that your /system is taking commands and the format looks like json. So lets stick to a slight variation of 2) and post exactly that command to your system:

/systemOrAnyThingYouOrFrameworkCameUpWith  { "command": "reboot", "message": "system going down", "delay":"now" } (of application/vnd.syscommand+json)

Your system also may have a shutdown script (or binary) and the command can be less explicit, because the recipient at /system/shutdown knows what is up:

/system/shutdownOrAnyThingYouOrFrameworkCameUpWith { reboot: true, "message": "system going down", "delay":"now" } (of application/vnd.shutdown+json)

In both cases, you ask for a change of state. So at least a POST is required.

A DELETE on those resource should result in a graceful shutdown (of course ;) ). But you will not be able to call that resource again.

Best,

Robert

[Kijana Woodard]

I would probably POST to /system/shutdown.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Jørn Wildt]

This would be make take at it: consider /system as a resource for representing the state of the system. This means your client can GET it:

Request:

GET /system

Response:

{

  running: true,

  memory: 2147483648,

  cpu: ...,

  ... other system details ...

}

Now your client have the full state of the /system resource, it can make local changes to them and PUT them back again (except that some properties are read-only of course):

Request:

PUT /system
{
  running: false,
  memory: 2147483648,

  cpu: ...,

  ... other system details ...
}

The use of "command" in requests are difficult to discover from a client side point of view. It works, its not wrong, but there is no way for the client to figure out that they exists - and it doesn't give you a natural resource to GET for retrieving the system state.

You could of course also use a media type with hypermedia elements for modifying state and then embed a "shutdown" action in the /system response ... but most people would probably think of this as a bit over engineered for an embedded system :-)

/Jørn

[Dmitry Pavlov]

Agree that PUT or PATCH (to modify only state, but not other properties) is a good solution.

Command solution could result in "rpc_like" style where you have one endpoint and a list of "actions" for it, so be carefull :)

С уважением,
Дмитрий Павлов

[wiki1000]

This is a typical case, another instance being the startup of a rocket.
You absolutely need to create a resource for this event, your name being inside, in the case of an audit.
It shall then be a POST to the list of all reboot events of your system, a side effect being the effective
reboot.


Cheers.

[Chris Mullins]

Personally, I don't have the issue with RPC API's that many folks have. Modeling everything as REST to me has always seemed needlessly dogmatic. 

Having a "Command API" that is RPC in style, but still offered over HTTP, seems a reasonable solution. Modeling a Command API as a Resource, and then poking at it, seems like you're forcing things.

I could see having a HATEOS model, where you access a "Computer" resource, and that resource has RPC style commands exposed as links.  

"GET /computer" could return options depending on state and user access such as:

{

  "shutdown":"https://foo.com/api/blablablabla/shutdown?when-now",

  "sleep":"https://foo.com/api/blablablabla/sleep?when=now",

  "hibernate":"https://foo.com/api/blablablabla/hibername?when=now",

}

My random thought for the say... :-) 

Cheers,

Chris

[Richard Mateosian]

Of course, and nobody will complain if you don't call it REST.  :-)   ...RM

On Wed, Feb 18, 2015 at 12:45 PM, Chris Mullins <cmul...@gmail.com> wrote:

Having a "Command API" that is RPC in style, but still offered over HTTP, seems a reasonable solution.

--

Richard Mateosian <x...@pacbell.net>
Berkeley, California

[Chris Mullins]

It's funny, but folks (myself included!) so frequently misuse the term REST that it's actually changed in meaning. 

What folks usually mean when they say REST:

• REST = API offered over HTTP without all the craziness of WS-* services. Maybe it even takes advantage of some HTTP features like PUT/POST/PATCH. 
  

What folks seldom mean:

• Properly modeled resourced and a true-to-form RESTful API. 

I always wonder if this comes from so many people building WebServices (WS-*) for years, and then seeing how much less complex it really needed to be...

Cheers,

Chris

[wiki1000]

about the suggestion to present in a HATEOAS way the activation of the reboot,
I would suggest to return on the GET of /computer the following Link headers:

Link:<>;rel="reboot";type=text/uri-list;accept-post=application/x-www-form-urlencoded,
<>;rel="reboot";accept-post=text/uri-list

The first link will, on GET returns all the reboot events of the past in the form of a possibly paginated list of uris,
and on POST of a small file, store the reboot event after or before having rebooted what you wanted to reboot.

The second link will only accept a POST of the uri of an existing reboot resource, and will execute it after having changed the date of the previous reboot event.
This allow to handle complex reboot behaviour, without having to retype the list of shutdowns to wait etc.

you will notice that the second way of doing is specially user friendly since it has absolutely nothing to know a priori in order to be operated, the reuse of an existing way being enough.