Pandoc API

A simple RESTful server for converting documents using pandoc

Install

pandoc is required for converting documents

# apt-get install pandoc
yarn add pandoc-api

Usage

Start a server in command-line:

yarn start

Get command line help

yarn --help

pandoc-api, a simple RESTful server for converting documents
  please visit https://github.com/alphakevin/pandoc-api

usage: pandoc-api <command> <options>

commands:
  start [<hostname>[:<port>]]  start the server, default to localhost:4000
  help converter             get converter help

options:
  -h, --help                 print this help message

Use in your application

import expores from 'express';
import pandoc from 'pandoc-api';

const app = express();
app.use('/pandoc', pandoc());
// ... your own express routes
app.listen(3000);

Converter

The server provides a similar interface like pandoc, you can simply remove -- or - and use / instead of white-space between the arguments, all after /api/convert.

POST /api/convert/from/<input-format>/to/<output-format> HTTP/1.1

You can upload file by either of the following method:

multipart/form-data upload with a file field of the file to be converted.
RAW upload a file in HTTP body with Content-Type and Content-Disposition header provided.

If the /output/<value> option is provided, the Content-Disposition header will contain the new filename.

The converted document will be directly output from the HTTP response body.

For more converting options, please visit https://pandoc.org/MANUAL.html

Environment Variables

Name	Description
`HOSTNAME`	For server listening hostname
`PORT`	For server listening port

Examples

Visit http://127.0.0.1:4000/help, or get help in command-line:

yarn cli help converter

Here we use cURL for examples.

Uploading with `multipart/form-data`

$ curl -F file=@example.docx http://127.0.0.1:4000/api/convert/from/docx/to/html > result.html

Uploading RAW Binary Data

$ curl -X POST \
  -T "example.docx" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -H "Content-Disposition: attachment; filename="example.docx"" \
  http://127.0.0.1:4000/api/convert/from/docx/to/html > result.html

Converting Options

  /e, /export/<value>     set export filter options
  /f, /format/<value>     specify the output format
  /F, /field/<value>      replace user-defined text field with value
  /i, /import/<value>     set import filter option string
  /o, /output/<value>     output basename, filename or directory
      /password/<value>   provide a password to decrypt the document

Run as Docker Container

pandoc-api can start from docker without source code or npm installed:

docker run -d -p 4000:4000 --name=pandoc --restart=always alphakevin/pandoc-api

Notice

This is a simple http server and supposed to run as inner micro-service, so it does not include any authorization method. Please take your own risk to deploy it publicly.
Document formats and options are not fully tested, it just pass them to pandoc.

License

MIT

zhaozhiyong19890102/pandoc-api