SignPuddle 3 Development Tools

SignPuddle 3 can be installed on a computer or USB drive. The source code is available using git.

# INSTALL
cd Desktop  

# Either install in a new SignPuddle3 directory
git clone https://github.com/slevinski/apitxt SignPuddle3

# Or install in current directory
git clone https://github.com/slevinski/apitxt .

Software updates are also available through git.

# UPDATE
cd SignPuddle3  
git pull

The server requires some configuration before it can be used.

# CONFIGURE
cd SignPuddle3/server  
unzip Slim.zip

If an Apache web server is not available, you can start the system using the PHP builtin server. While the client code can function without a webserver, the server code requires a web server to function.

# START
cd SignPuddle3/system  
  
# Windows  
start_system.bat  

# Mac or Linux  
./start_system.sh  

Once started, SignPuddle 3 will be available on the same computer with two default URLs.

• http://localhost:8888/

• http://0.0.0.0:8888/

To access SignPuddle 3 on a different computer or device, use the computer’s individual IP Address available from the output of the start_system script.

./start_system.sh
        inet 192.168.254.6 netmask 0xffffff00 broadcast 192.168.254.255
PHP 7.1.16 Development Server started at Wed Sep 19 11:15:04 2018
Listening on http://0.0.0.0:8888
Document root is /Users/slevinski/Desktop/SignPuddle3
Press Ctrl-C to quit.

In this example, SignPuddle 3 will be available with this URL.

• http://192.168.254.6:8888

Most users will access SignPuddle 3 with the client section: a combination of HTML, CSS, and JavaScript. The client section presents information graphically.

The client section can be used online or downloaded as part of the ApiTxt project. The client section can be opened using the file system and any standard browser.

Application

• client

• https://SignPuddle.com/client

Resources

• Source: ApiTxt format and JSON objects

• Documents: API Blueprint and Stand Alone HTML

• Live Page: API Interface and JavaScript

The server section is a functional RESTful API written in PHP using the Slim Framework v2.

The server section requires an Apache webserver that can use rewrite rules. The rules are written in the server/.htaccess file.

Alternatively, the server section can use the built-in PHP webserver. See the system directory for more information.

Application

• server

• https://SignPuddle.com/server

Document segments are written in the source directory using ApiTxt Format: a highly structured plain text markup that fully defines a RESTful API. Each line in an ApiTxt document is a self-contained element which starts with a name and is followed by <TAB> separated fields.

ApiTxt Format uses eleven types of element to define an RESTful API: root, group, route, parameter, method, request, response, header, line, code, and body.

Python programs and shell scripts are used to read and write a variety of data formats including ApiTxt Format, JSON data, API Blueprint, HTML, JavaScript, and PHP scripts.

• txt2json.py - From ApiTxt Format to an array of JSON objects.

• json2txt.py - From an array of JSON objects back to ApiTxt Format.

• json2md.py - From an array of JSON objects to API Blueprint written in markdown.

• json2php.py - From an array of JSON objects to a functional PHP server using the Slim Framework v2.

• json2html.py - From an array of JSON objects to API Interface.

• json2js.py - From an array of JSON objects to JavaScript.

All of the tools use command line arguments. Use -h for help.

python txt2json.py -h
usage: txt2json.py [-h] [-i INPUT] [-o OUTPUT] [-e]

Conversion of plain text lines to an array of JSON objects

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        name of input file
  -o OUTPUT, --output OUTPUT
                        write to output file
  -e, --errors          check for errors and report

Make and Build

The tools/make.sh file is used to create the build script.

The tools/build.sh file is used to create the client and server sections.

cd SignPuddle3/tools
./make.sh
./build.sh

Snowboard (bukalapak/snowboard)

Used in the build script, snowboard can parse API Blueprint documents. Snowboard offers three different transformations: lint, html, and mock. Snowboard lint will check the structure of the markdown text and report errors. Snowboard html will create a stand-alone html document using a template. Snowboard mock will analyze the responses of the markdown document and serve static responses over HTTP.

The system directory contains a portable web server for Windows, Linux, and Mac. The system directory is useful for individual computers or private networks.

For public servers, do not use the system directory, instead use the Apache web server with rewrite rules.