diff options
| author | hallgren <hallgren@chalmers.se> | 2012-06-18 15:18:02 +0000 |
|---|---|---|
| committer | hallgren <hallgren@chalmers.se> | 2012-06-18 15:18:02 +0000 |
| commit | 3d5efdd2d26f5c411891fc1cf56e6a2ebbf91a66 (patch) | |
| tree | fe7dc6bdd5914ccf053c347c31c3e3d710d18313 /src/www/gf-cloud-api.html | |
| parent | 71da0126266701e91903e8fe59066d4a008a2cfa (diff) | |
GF cloud api doc fixes
Diffstat (limited to 'src/www/gf-cloud-api.html')
| -rw-r--r-- | src/www/gf-cloud-api.html | 69 |
1 files changed, 47 insertions, 22 deletions
diff --git a/src/www/gf-cloud-api.html b/src/www/gf-cloud-api.html index 5549764d1..b21817b97 100644 --- a/src/www/gf-cloud-api.html +++ b/src/www/gf-cloud-api.html @@ -6,31 +6,52 @@ <meta name = "viewport" content = "width = device-width"> <style type="text/css"> dl.api>dt, .request { background-color: #cef; } -dl.api>dd code, .response { background-color: #ffc; } +.response { background-color: #ffc; } +dd { margin-top: 0.5ex; margin-bottom: 0.5ex; } </style> </head> <body> -<h1><img class=nofloat src="P/gf-cloud.png" alt=""> GF Cloud Service API (preliminary)</h1> +<h1><a href="./"><img src="P/gf-cloud.png" alt=""></a> GF Cloud Service API (preliminary)</h1> The GF cloud service API provides the following functionality: <ul> - <li>The functionalty available in via the <strong>PGF service API</strong>, - <li>The functionality provided by the commands in <strong>GF shell</strong>, + <li>the functionality available in via the <strong>PGF service API</strong>, + <li>the functionality provided by the commands in the + <strong>GF shell</strong>, <li>some additional services for grammar compilation and persistent storage of files in the cloud. </ul> + +<p> +<strong>This is preliminary and subject to change!</strong> + +<h2>Availability and protocol</h2> <p> The service is available from -<a href="http://cloud.grammaticalframework.org"><code>http://cloud.grammaticalframework.org</code></a>. +<a href="http://cloud.grammaticalframework.org/"><code>http://cloud.grammaticalframework.org/</code></a>. Users that have GF installed on their own computer can also run the service locally by starting GF with the command <code>gf -server</code>. <p> +Requests are made via HTTP with the GET or POST method. (The examples below +show GET requests, but POST is preferred for requests that change the state +on the server.) +<p> +Data in requests is in the <code>application/x-www-form-urlencoded</code> format +(the format used by default by web browsers when submitting form data). +<p> +Data in responses is usually in JSON format. +The HTTP response code is usually 200, but can also be +204 (after file upload), +404 (file to download or remove was not found), +400 (for unrecognized commands or missing/unacceptable parameters in requests) +or +501 (for unsupported HTTP request methods). -<strong>This is preliminary and subject to change!</strong> +<h2>Requests</h2> <h3>PGF Service</h3> @@ -57,14 +78,17 @@ For more info, see: <h3>GF Shell Service</h3> This service lets you execute arbitrary GF shell commands. Before you can do this, you need to use the <code class=request>/new</code> command to obtain a -working directory (which also servces as a session identifier) on the server, +working directory (which also serves as a session identifier) on the server, see below. <dl class=api> - <dt><code>/gfshell&dir=</code>...<code>&command=i+Foods.pgf</code> + <dt><code>/gfshell?dir=</code>...<code>&command=i+Foods.pgf</code> <dd> - <dt><code>/gfshell&dir=</code>...<code>&command=gr</code> - <dd><code>Pred (That Pizza) (Very Boring)</code> + <dt><code>/gfshell?dir=</code>...<code>&command=gr</code> + <dd class=response><code>Pred (That Pizza) (Very Boring)</code> + <dt><code>/gfshell?dir=/tmp/gfse.t6GFEY6b/&command=ps+-lextext+%22That+pizza+is+very+boring.%22</code> + <dd class=response><code>that pizza is very boring .</code> + </dl> For documentation of GF shell commands, see: @@ -77,9 +101,9 @@ For documentation of GF shell commands, see: <dl class=api> <dt><code>/new</code> <dd>This generates a new working directory on the server, e.g. - <code>/tmp/gfse.123456</code>. - Most of the clouds service commands require that a working directory - is specified in the <code>dir</code> parameter. + <code class=response>/tmp/gfse.123456</code>. + Most of the cloud service commands require that a working directory + is specified in the <code class=request>dir</code> parameter. The working directory is persistent, so clients are expected to remember and reuse it. Access to previously uploaded files requires that the same working directory is used. @@ -87,18 +111,19 @@ For documentation of GF shell commands, see: <dd>This command can be used to check GF source code for syntax errors. It also converts GF source code to the JSON representation used in GFSE (the cloud-based GF grammar editor). - <dt><code>/cloud?&dir=</code>...<code>&command=upload&</code><var>path<sub>1</sub></var><code>=</code><var>source<sub>1</sub></var><code>&</code><var>path<sub>2</sub></var><code>=</code><var>source<sub>2</sub></var><code>&</code>... + <dt><code>/cloud?dir=</code>...<code>&command=upload&</code><var>path<sub>1</sub></var><code>=</code><var>source<sub>1</sub></var><code>&</code><var>path<sub>2</sub></var><code>=</code><var>source<sub>2</sub></var><code>&</code>... <dd>Upload files to be stored in the cloud. - <dt><code>/cloud?&dir=</code>...<code>&command=make&</code><var>path<sub>1</sub></var><code>=</code><var>source<sub>1</sub></var><code>&</code><var>path<sub>2</sub></var><code>=</code><var>source<sub>2</sub></var><code>&</code>... + <dt><code>/cloud?dir=</code>...<code>&command=make&</code><var>path<sub>1</sub></var><code>=</code><var>source<sub>1</sub></var><code>&</code><var>path<sub>2</sub></var><code>=</code><var>source<sub>2</sub></var><code>&</code>... <dd>Upload grammar files and compile them into a PGF file. - <dt><code>/cloud?&dir=</code>...<code>&command=download&file=</code><var>path</var> + The response code is 204 if the upload was successful. + <dt><code>/cloud?dir=</code>...<code>&command=download&file=</code><var>path</var> <dd>Download the specified file. - <dt><code>/cloud?&dir=</code>...<code>&command=ls&ext=.pgf</code> - <dd><code>["Foods.pgf","Letter.pgf"]</code> (list files with the specified extension) - - <dt><code>/cloud?&dir=</code>...<code>&command=rm&file=</code><var>path</var> + <dt><code>/cloud?dir=</code>...<code>&command=ls&ext=.pgf</code> + <dd>List files with the specified extension, e.g. + <code class=response>["Foods.pgf","Letter.pgf"]</code>. + <dt><code>/cloud?dir=</code>...<code>&command=rm&file=</code><var>path</var> <dd>Remove the specified file. - <dt><code>/cloud?&dir=</code>...<code>&command=link_directories&newdir=</code>... + <dt><code>/cloud?dir=</code>...<code>&command=link_directories&newdir=</code>... <dd>Combine server directores. This is used by GFSE to share grammars between multiple devices. </dl> @@ -106,7 +131,7 @@ For documentation of GF shell commands, see: <hr> <address></address> <div class=modtime><small> -<!-- hhmts start --> Last modified: Mon Jun 18 15:03:02 CEST 2012 <!-- hhmts end --> +<!-- hhmts start --> Last modified: Mon Jun 18 17:13:51 CEST 2012 <!-- hhmts end --> </small></div> <address> <a href="http://www.cse.chalmers.se/~hallgren/">TH</a> |