# GF Cloud Service API (preliminary)

The GF cloud service API provides the following functionality:

- the functionality available in via the PGF service API,
- the functionality provided by the commands in the GF shell,
- some additional services for grammar compilation and persistent storage of files in the cloud.

This is preliminary and subject to change!

## Availability and protocol

The service is available from `http://cloud.grammaticalframework.org/`. Users that have GF installed on their own computer can also run the service locally by starting GF with the command `gf -server`.

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.)

Data in requests is in the `application/x-www-form-urlencoded` format (the format used by default by web browsers when submitting form data).

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). Unrecognized parameters in requests are silently ignored.

## Requests

### PGF Service

The GF Cloud Service supports the same set of PGF service requests as the already available PGF web service. For example, a request like

> `http://cloud.grammaticalframework.org/grammars/Foods.pgf?command=random`

might return a result like

> `[{"tree":"Pred (That Pizza) (Very Boring)"}]`

For more info, see:

- PGF web service API examples.
- PGF web service API documentation.

### GF Shell Service

This service lets you execute arbitrary GF shell commands. Before you can do this, you need to use the `/new` command to obtain a working directory (which also serves as a session identifier) on the server, see below.

`/gfshell?dir=`...`&command=i+Foods.pgf`
`/gfshell?dir=`...`&command=gr`
  `Pred (That Pizza) (Very Boring)`
`/gfshell?dir=`...`&command=ps+-lextext+%22That+pizza+is+very+boring.%22`
  `that pizza is very boring .`

For documentation of GF shell commands, see:

- GF Shell Reference

### Additional cloud service

`/new`
  This generates a new working directory on the server, e.g. `/tmp/gfse.123456`. Most of the cloud service commands require that a working directory is specified in the `dir` 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.
`/parse?`path`=`source
  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).
`/cloud?dir=`...`&command=upload&`path1`=`source1`&`path2`=`source2`&`...
  Upload files to be stored in the cloud. The response code is 204 if the upload was successful.
`/cloud?dir=`...`&command=make&`path1`=`source1`&`path2`=`source2`&`...
  Upload grammar files and compile them into a PGF file. Example response:

  > `{ "errorcode":"OK", // "OK" or "Error"
  > "command":"gf -s -make FoodsEng.gf FoodsSwe.gf FoodsChi.gf",
  > "output":"\n\n" // Warnings and errors from GF
  > }`

`/cloud?dir=`...`&command=remake&`path1`=`source1`&`path2`=`source2`&`...
  Like `command=make`, except you can leave the sourcei parts empty to reuse previously uploaded files.
`/cloud?dir=`...`&command=download&file=`path
  Download the specified file.
`/cloud?dir=`...`&command=ls&ext=.pgf`
  List files with the specified extension, e.g. `["Foods.pgf","Letter.pgf"]`.
`/cloud?dir=`...`&command=rm&file=`path
  Remove the specified file.
`/cloud?dir=`...`&command=link_directories&newdir=`...
  Combine server directores. This is used by GFSE to share grammars between multiple devices.

Last modified: Tue Jun 17 10:42:21 CEST 2014