source: other-projects/the-macronizer/trunk/README.md

# Macroniser API Setup

1. Edit the HTML content of the `unauthorised` page so that the button redirects to your preferred location.

    ```sh
    nano src/main/webapp/webContent/unauthorised.html
    ```

2. Compile and install the WAR file.

    ```sh
    > ant install
    ```

3. Update the apache2 config with the relevant `ProxyPass` rules

    ```sh
    > sudo nano /etc/apache2/sites-enabled/000-default-le-ssl.conf
    > sudo nano /etc/apache2/sites-enabled/000-default.conf
    > sudo /etc/init.d/apache2 reload
    
    // ADD THE FOLLOWING
    ProxyPass /gs3-macroniser http://localhost:8383/gs3-macroniser
    ProxyPassReverse /gs3-macroniser http://localhost:8383/gs3-macroniser
    ```

4. If `403 Forbidden` errors are observed, update the CORS filter in `web.xml` to include your root domains, and re-install.

    ```sh
    > nano src/main/webapp/WEB-INF/web.xml

    <filter>
        <filter-name>CorsFilter</filter-name>
        <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
        <init-param>
            <param-name>cors.allowed.origins</param-name>
            -- <param-value>http://localhost:8080</param-value> <!-- Separate values by a comma -->
            ++ <param-value>http://localhost:8080,http://atea.space,https://atea.space</param-value>
        </init-param>
    </filter>
    ```

### Usage outside of Tomcat/Greenstone3

The Macroniser API was designed with Greenstone3 in mind. Hence, it expects an Apache Tomcat server and the ant installation task is specific to Greenstone3.
If you need to use this API in a different environment, there are two steps you'll need to take:

1. If you'll not be hosting the servlet in Tomcat, update the class of the CORS filter in `web.xml`. An example for a Jetty server is provided.

2. Manually install the WAR file to your server. It can be generated with the ant `package` task, which outputs it to `./build/gs3-macroniser.war`.

    ```sh
    > ant package
    ```

If you'd like a quickstart in a non-greenstone environment, the `dev-deploy.tar.gz` archive contains standalone bundles of Ant and Jetty that you can utilise.

# Consuming the API

## Direct Macronisation

- Endpoint: `/direct`
- Method: `POST`
- Request Content Type: `multipart/form-data`
- Response Content Type: `application/json`

The `direct` endpoint macronises and returns raw text.

### Expected Form Parts

Name | Type | Optional | Description
--|--|--|--
`fragment` | `string` | No | The fragment to macronise
`preserveExistingMacrons` | `boolean` | Yes (default: `false`) | A value indicating whether or not existing macrons on the input text will be preserved.

### Response Fields

Name | Type | Optional | Description
--|--|--|--
`w` | `string` | Yes | A processed word word.
`macronised` | `boolean` | Yes | A value indicating whether the associated `w` value was macronised.
`linebreaks` | `number` | Yes | Indicates a number of linebreaks encountered in the original text.

#### Example Response

```json
[
    {
        "w": "Whakaora"
    },
    {
        "w": "Tohutō",
        "macronised": true
    },
    {
        "w": "Māori",
        "macronised": true
    },
    {
        "linebreaks": 3
    }
]
```

## File Macronisation

- Endpoint: `/file`
- Method: `POST`
- Request Content Type: `multipart/form-data`
- Response Content Type: `application/json`

The `file` endpoint macronises a single file. The resulting macronised file is stored temporarily and can be retrieved using the `download` endpoint.
The endpoint can be used multiple times to macronised more than one file.

Supported formats:

- Plain Text (.txt)
- Microsoft Powerpoint (.pptx)
- Microsoft Word (.docx)
- Open Document Text (.odt)

### Expected Form Parts

Name | Type | Optional | Description
--|--|--|--
`charsetEncoding` | `string` | Yes (default: `utf8`) | The character set used by the file.
`fileType` | `string` | Yes (default: extension of the submitted file) | The type of the submitted file (e.g. `.pptx`, `.txt`).
`preserveExistingMacrons` | `boolean` | Yes (default: `false`) | A value indicating whether or not existing macrons on the input text will be preserved.
`file` | File data | No | The file to macronise.

### Response Fields

Name | Type | Optional | Description
--|--|--|--
`fileName` | `string` | No | The name of the macronised file.
`filePath` | `string` | No | The path to submit to the `download` endpoint in order to retrieve the file.
`fileType` | `string` | No | The type of the macronised file (e.g. `.pptx`, `.txt`).

#### Example Response

```json
{
    "fileName": "macron-text.txt",
    "filePath": "mi-tmp-7501722420086381909.txt",
    "fileType": ".txt"
}
```

## File Download

- Endpoint: `/download`
- Method: `GET`
- Response Content Type: `application/x-download`

The `download` endpoint provides access to files macronised via the `file` endpoint.

### Expected Paramters

Name | Type | Optional | Description
--|--|--|--
`filepath` | `string` | No | The path to retrieve the file at. Sent in the response from a call to the `file` endpoint.
`fileType` | `string` | No | The name to use in the download response.