REST in reality
How to RESTfully change the state of power lines and poles? From a thread on the OGC's mass-market-geo list (archives available only to subscribers, for shame):
Actually, I am really talking about poles and wires. Specifically power poles and lines. My example is directly derived from real life. A local electric system has tons of old wood poles that it wants to replace with concrete poles. It is doing this by installing the concrete pole 1m behind the existing pole and then restringing the power lines.
So, the client has a feature type POLES (Oracle table) with all the poles and a feature type LINES (Oracle table) with all the power lines. Not the actual named but you get the idea.
For each pole that is replaced, they update the existing pole record since the new pole will have the same pole id as the pole it replaces but the new pole will be in a slight different position.
Using the current WFS specification, I can make these changes in a single request. I simply POST the following the the URL of the server:
<wfs:Transaction>...
The question of how to do this in a single transaction is a big juicy red herring that has list subscribers rather distracted. The process of disconnecting and taking down wires takes some time, and presumably has to be done before you can take down the pole they connect to. Certainly the new pole can't be erected before the old one is torn down, and only after that happens can new lines be brought in to connect to the new pole. This is not an atomic operation. Bad weather, equipment failure, injury, or any mishap might interrupt the process and leave it an unfinished state for some time. Treating it as atomic in your information system seems more hopeful than realistic, and perhaps even harmful. Once the lines and poles come down, you can't be giving anyone the false impression that they're still up.
Let's say you've modeled your power system RESTfully. You've got pole resources like http://example.com/power/poles/1. You've line resources like http://example.com/power/lines/1 and http://example.com/power/lines/2. These resources aren't poles and lines by virtue of the strings in the URI, of course, that's just a convenient design. Lines 1 and 2 connect at pole 1. A utility crew keeps your information system up to date as they work like this:
DELETE lines http://example.com/power/lines/1 and http://example.com/power/lines/2 as they are physically dismantled.
DELETE pole http://example.com/power/poles/1 as it's cut down and dragged away.
PUT new state (new location, new material attributes, etc) to http://example.com/power/poles/1 when the new pole is up.
PUT new state (new lengths, etc) to lines http://example.com/power/lines/1 and http://example.com/power/lines/2 after they've been reconnected.
This isn't finance. Sometimes non-transactional is more honest.
Comments
Re: REST in reality
Author: Gary Sherman
In reality the new poles will all be installed (1 m behind existing), then the lines will be moved all at once.
Re: REST in reality
Author: Sean
I was imaging the lines would be upgraded too. If not, even easier: PUT new state (new location, new material attributes, etc) to http://example.com/power/poles/1 when the lines are hung on the new pole. Don't change the state of the line at all.
Re: REST in reality
Author: Jason Birch
Keeping the same id feels a bit contrived. Normally, you'd want to retain the old ID in a "removed" state for asset managment reporting on upgrade history, service lifetime, etc, etc. So, in this case, I think you'd PUT the new state (retired) to the old pole, and POST a new pole.
Typically a line is connected to many poles, and a pole can have many lines strung on it. Assuming this relationship was modeled by GETing lists of hyperlinks from the following URIs (don't know if this is "correct"):
GET http://example.com/power/poles/1/lines
GET http://example.com/power/lines/1/poles
How would you move the lines from one pole to another?
DELETE http://example.com/power/poles/1/lines/1
POST http://example.com/power/poles/2/lines/1
That seems a bit odd to me, because you wouldn't
GET http://example.com/power/poles/2/lines/1
Separate "service"?
DELETE http://example.com/power/pole/1/lines {content: 1,2,5,61}
POST http://example.com/power/pole/2/lines {content: 1,2,5,61}
Re: REST in reality
Author: Cedric Moullet
Jason's use case is quite interesting. I was thinking to another one: usually, when line modification occurs, a mailing is done in order to inform the customers of the outage (typical question: provide me the list of all customers affected by the deletion of this line).
What would be the correct URI for this kind of question ?
Re: REST in reality
Author: Sean
I'm not sure what you mean by URI for the question. If you designed a system such that the customers for each line (or segment of the power grid? I'm getting out of my depth, here) were enumerated in a resource like http://example.com/power/lines/1/customers, you might have a form to which you could POST a message like http://example.com/power/lines/1/customers/notice (delivered by email and snail mail).