#330 More URIs? RESTful PE?

[Lee Worden]

We are using URIs to refer to projects uniquely (of the form scheme:repository:path or scheme:repository/path depending on the scheme). We also implicitly have URIs for wikis - that is, we use the base WWW URL of the wiki up to but not including index.php. Also, we embed the wiki's URI in its projects' URIs by using it as the repository location in the pe-ww URI scheme.

In the future we'll probably assign a URI to the project engine itself, allowing a wiki to control which project engine(s) it connects to. Since ProjectEngine is designed to work as an HTTP service, this will probably also be a base URL, even though the client may use internal function calls rather than HTTP to access it.

This morning it occurred to me that we can do more - why shouldn't we support a URI like project-file:project-engine-uri//project-uri/filename? Wouldn't that make it really simple to put project files lots of places? For instance, we could have a really simple WordPress extension that doesn't do anything except support project-file URIs by making a simple uniform request to the project engine and displaying the result.

I guess it isn't much different from a syntax like <project-file project-engine="X" project="Y" filename="Z"/>, but there must be benefits to using the standard URI convention. For one thing, it's a single standard for use in all clients, whereas we would probably end up having those XML-style tags in wikis and some completely other kind of syntax in WordPress, another one in Perl function calls, etc.

[Lee Worden]

inspired by

http://en.wikipedia.org/wiki/Representational_State_Transfer

which also suggests other improvements to ProjectEngine design, such as principled use of GET, PUT, POST, DELETE. Which I'm not inclined to worry about until I see a clear reason to.

[Lee Worden]

Ticket moved from /p/workingwiki/feature-requests/20/

[Lee Worden]

See [#448] for a situation where this would be helpful.

What would it take to get it up and running, if incomplete?

• teach PE to respond to HTTP requests directly. It already does, actually, but using a sort of unintuitive, convoluted request syntax. You have PE in some directory in the website, and then its URL is http://server.name/PE-directory/index.php?arguments=values.
• Provide a URL for WW to pass requests through to PE, in the case where PE isn't installed separately from WW. This might be http://server.name/wiki-url/index.php/Special:PE?arguments=values.
• Let http://PE-URL be either http://server.name/PE-directory/index.php or http://server.name/wiki-url/index.php/Special:PE.
• provide an HTTP GET interface for files. I.e. http://PE-URL/project-name/filename. This would just plain retrieve a file, if it's there. Note that this "project-name" is a project name that PE understands, not one that some wiki understands, i.e. it's probably a full project URI. The project name has to be URL-encoded, with all slashes, colons, etc. written as hex codes beginning with %, so that the full PE URL is well-formed.
• the next step would be a make operation: http://PE-URL/project-name/filename?make=1
  • this would make and then retrieve the file
• and a sync operation, which is HTTP PUT rather than GET, with the same URL as GET - http://PE-URL/project-name/filename - but with the file contents provided, to be written to the directory rather than retrieved.
• an implementation of HTTP DELETE that does the obvious thing.
• But make, PUT, and DELETE can be left for some other time.
• What I need now, if I do [#448] this way, is a way to stream out a logfile in SSE events, for consumption by a Comet client. I guess that would be as simple as http://PE-URL/logfiles/logfilename?format=sse.
• I would also need an interface to send discrete status updates to PE to be appended to that logfile - easy to do - and a flag to tell it to dump the output of make (and other operations) into the appropriate logfile while it's running - also an easy interface to design, though there might be some work involved in getting the dumping to happen.

[Note: I stubbed in a security layer for PE, with the idea that you might have to provide a password to get access to the files. This business here would require the client to have a password as well as the server. It might also require some work on CORS (Cross-Origin Resource Sharing - how to authorize a website on one host to access URLs on a different host). Frankly, I can cross those bridges when I come to them.]

[Lee Worden]

I think I want to use the page name Special:PE for the URL to pass requests unmediated to ProjectEngine. It's possible that that name's too short and will risk collision with other extensions' special page names. Opinions, anyone?

[Lee Worden]

Re make, I think actually make should probably be an HTTP POST operation that returns the updated file contents. Or it might be a separate operation, called via POST, that returns yes/no, and you have to follow it with a GET to retrieve the contents.

[Lee Worden]

Yo, instead of Special:PE, which is ugly, I should probably provide a 'ww-pass-to-pe' API action, which can be used for API calls to PE (obviously), as well as directly in browsers as, for instance, raw URLs for image files.