root	apitxt	ApiTxt	https://signpuddle.com/server
	line	> v2.0.0
	line	
	line	ApiTxt is the build environment to create the SignPuddle 3 API for SignWriting Text.
	line	ApiTxt format is a highly structured plain text format that defines multiple facets of a website api.
	line	
	line	A variety of python programs and shell scripts are used to transform the source ApiTxt format into a fully functional and documented website.
	line	
	line	## Input and Output Formats
	line	The various formats are used to define the structure and function of a website API.
	line	The original source is written in ApiTxt format and transformed into an array of JSON objects.
	line	The JSON objects are used to write other formats, including API Blueprint.
	line	API Blueprint has an extensive toolkit of additional transformations.
	line	
	line	### ApiTxt Format (txt)
	line	ApiTxt defines a highly structured plain text format used to define multiple facets of a website api.
	line	Each line in an ApiTxt document is a self-contained element which starts with a name and is followed by <TAB> separated fields.
	line	Writing ApiTxt documents is easier when tabs and spaces appear different, so use a plain text editor and turn on the invisible characters option.
	line	
	line	### Array of JSON Objects (json)
	line	Each line of ApiTxt format is converted into a JSON object or added to an existing object.
	line	The various objects are stored as an ordered array.
	line	The JSON array of objects can be reduced to the root object by appropriately structuring the groups, routes, and methods.
	line	
	line	```
	line	    root
	line	      | - routes
	line	            | - methods
	line	      | - groups
	line	            | - routes
	line	                  | - methods
	line	```
	line	
	line	
	line	### API Blueprint (md)
	line	[API Blueprint](https://apiblueprint.org/) is a high-level API description language for web APIs. API Blueprint is widely supported with various tooling available.
	line	
	line	### Stand-Alone HTM Documentation (htm)
	line	Stand-alone HTM document created from the API Blueprint using a template and the snowboard tool.
	line	
	line	### Interactive HTML API (html)
	line	Interactive HTML documentation is generated from the JSON elements.
	line	
	line	### PHP Server (php)
	line	The PHP server is written for the PHP project [Slim Framework v2](https://docs.slimframework.com/) to create the functional web API.
	line	The website directory contains an .htaccess file for an Apache server with PHP support.
	line	Alternatively, the server can be started with a shell script (start_server.sh) using PHP's built in web server and a custom rewrite.php file.
	line	
group	apitxt	ApiTxt uses eleven types of element to define an API.
	line	root, group, route, parameter, method, request, response, header, line, code, and body.
	line	
	line	+ Source: [ApiTxt format](../src/apitxt.txt) and [JSON objects](../src/apitxt.json)
	line	+ Documents: [API Blueprint](../doc/apitxt.md) and [Stand Alone HTML](../doc/apitxt.htm)
	line	+ Live Page: [API Interface](../api/apitxt.html) and [JavaScript](../api/apitxt.js)
	route	/apitxt/root	root
		line	Every document should start with a root element.
		line	After the root, the other elements are used to quickly create complex website APIs.
		line	The order of the lines matters and will effect the structure of the JSON objects.
		line	
		line	There are two groups of elements, the frame elements and the detail elements.
		line	The frame elements structure a website api and the detail elements attach to a previous frame element.
		line	
		line	### Frame elements
		line	There are six frame elements: root, group, route, method, request, and response.
		line	The lines are written in a specific order to create an array of JSON objects.
		line	
		line	**route organization**
		line	
		line	An ApiTxt document starts with a root, or an assumed root.
		line	Any route that occur before a group element, will be associated with the root.
		line	Groups are always associated with the root.
		line	Group elements can contain routes.
		line	
		line	```
		line	    root
		line	      | - routes
		line	      | - groups
		line	            | - routes
		line	```
		line	
		line	**route structure**
		line	
		line	A route can be associated with a variety of HTTP methods.
		line	Each method can have several requests and responses.
		line	Any response before a request will assume a generic request.
		line	Any response after a request will be associated with that request.
		line	
		line	```
		line	    route
		line	      | - methods
		line	        | - responses
		line	        | - requests
		line	              | - responses
		line	```
		line	
		line	## Detail elements
		line	There are five detail elements: line, parameter, code, header, and body.  The detail lines attach to a previous frame element if correctly structured.
		line	
		line	**single line elements**
		line	
		line	+ lines for all frame elements
		line	+ parameters for route
		line	+ code for method
		line	+ body for request and response
		line	+ headers for request and response
		line	
		method	GET	Get root definition
			line	Every document should start with a root element.
			line	
			line	**root line**
			line	
			line	root <TAB> name <TAB> title <TAB> host
			line	
			line	+ field 1 - name - uniquely identifies a document
			line	+ field 2 - title - name of the document
			line	+ field 3 - host - website URL
			line	
			line	**root example**
			line	
			line	root <TAB> apitxt <TAB> ApiTxt <TAB> https://signpuddle.com/apitxt
			line	
			line	
			line	**root line relationships**
			line	
			line	```
			line	    root
			line	     | - lines
			line	     | - routes
			line	     | - groups
			line	```
			line	
			line	**root object**
			line	
			line	```json
			line	{
			line	  "root" : field[1],
			line	  "title" : field[2],
			line	  "host" : field[3],
			line	  "lines" : []
			line	}
			line	```
			line	
			request	the root definition
				response	200	text/plain
					body	Every document should start with a root element.
					body	
					body	**root line**
					body	
					body	root<TAB>name<TAB>title<TAB>host
					body	
					body	+ field 1 - name - uniquely identifies a document
					body	+ field 2 - title - name of the document
					body	+ field 3 - host - website URL
					body	
					body	**example**
					body	
					body	root<TAB>apitxt<TAB>ApiTxt<TAB>https://signpuddle.com/apitxt
					body	
					body	
					body	**root line relationships**
					body	
					body	```
					body	    root
					body	     | - lines
					body	     | - routes
					body	     | - groups
					body	```
					body	
					body	**root object**
					body	
					body	```json
					body	{
					body	  "root" : field[1],
					body	  "title" : field[2],
					body	  "host" : field[3],
					body	  "lines" : []
					body	}
					body	```
	route	/apitxt/group	group
		method	GET	Get group definition
			line	The group organizes resources into sections
			line	
			line	**group line**
			line	
			line	group &lt;TAB> name &lt;TAB> description
			line	
			line	+ field 1 - name - the short name used for sections
			line	+ field 2 - description - information about the group
			line	
			line	**group example**
			line	
			line	group &lt;TAB> Section name &lt;TAB> an example section
			line	
			line	**group line relationships**
			line	
			line	```
			line	    group
			line	     | - lines
			line	     | - routes
			line	```
			line	
			line	**group object**
			line	
			line	```json
			line	{
			line	  "group" : field[1],
			line	  "description" : field[2],
			line	  "lines": []
			line	}
			line	```
			line	
			request	the group definition
				response	200	text/plain
					body	The group organizes resources into sections
					body	
					body	**group line**
					body	
					body	group<TAB>name<TAB>description
					body	
					body	+ field 1 - name - the short name used for sections
					body	+ field 2 - description - information about the group
					body	
					body	**group example**
					body	
					body	group<TAB>Section name<TAB>an example section
					body	
					body	**group line relationships**
					body	
					body	```
					body	    group
					body	     | - lines
					body	     | - routes
					body	```
					body	
					body	**group object**
					body	
					body	```json
					body	{
					body	  "group" : field[1],
					body	  "description" : field[2],
					body	  "lines": []
					body	}
					body	```
	route	/apitxt/route	route
		method	GET	Get route definition
			line	The route element allows access to a resource
			line	
			line	**route line**
			line	
			line	route &lt;TAB> URI template &lt;TAB> name &lt;TAB> description
			line	
			line	+ field 1 - URI template - a resource pattern with parameters
			line	+ field 2 - name - the route name must be unique
			line	+ field 3 - description - information about the resource
			line	
			line	**route example**
			line	
			line	route &lt;TAB> /example &lt;TAB> an example route &lt;TAB> a description of the route
			line	
			line	**route line relationships**
			line	
			line	```
			line	    route
			line	     | - lines
			line	     | - parameters
			line	     | - methods
			line	```
			line	
			line	**route object**
			line	
			line	```json
			line	{
			line	  "route" : field[1],
			line	  "name" : field[2],
			line	  "description" : field[3],
			line	  "lines": [],
			line	  "parameters": []
			line	}
			line	```
			line	
			request	the route definition
				response	200	text/plain
					body	The route element allows access to a resource
					body	
					body	**route line**
					body	
					body	route<TAB>URI template<TAB>name<TAB>description
					body	
					body	+ field 1 - URI template - a resource pattern with parameters
					body	+ field 2 - name - the route name must be unique
					body	+ field 3 - description - information about the resource
					body	
					body	**route example**
					body	
					body	route<TAB>/example<TAB>an example route<TAB>a description of the route
					body	
					body	**route line relationships**
					body	
					body	```
					body	    route
					body	     | - lines
					body	     | - parameters
					body	     | - methods
					body	```
					body	
					body	**route object**
					body	
					body	```json
					body	{
					body	  "route" : field[1],
					body	  "name" : field[2],
					body	  "description" : field[3],
					body	  "lines": [],
					body	  "parameters": []
					body	}
					body	```
	route	/apitxt/parameter	parameter
		method	GET	Get parameter definition
			line	The parameter element is applied to the previous route
			line	
			line	**parameter line**
			line	
			line	parameter &lt;TAB> name &lt;TAB> example &lt;TAB> type &lt;TAB> description
			line	
			line	+ field 1 - name - the name of a parameter for a route
			line	+ field 2 - example - an example value for the parameter
			line	+ field 3 - type - the parameter type, such as "string", "number", "boolean", "string, optional", "string, required"
			line	+ field 4 - description - information about the parameter
			line	
			line	**parameter example**
			line	
			line	parameter &lt;TAB> country_code &lt;TAB> US &lt;TAB> string &lt;TAB> the country code of interest
			line	
			line	**parameter line relationships**
			line	
			line	parameter lines are added to a parameters array
			line	
			line	**parameters array**
			line	
			line	```json
			line	{"parameters":
			line	  [
			line	    {
			line	      "name" : " field[1],
			line	      "example" : field[2],
			line	      "type" : field[3],
			line	      "description" : field[4]
			line	    }
			line	  ]
			line	}
			line	```
			line	
			request	the parameter definition
				response	200	text/plain
					body	The parameter element is applied to the previous route
					body	
					body	**parameter line**
					body	
					body	parameter<TAB>name<TAB>example<TAB>type<TAB>description
					body	
					body	+ field 1 - name - the name of a parameter for a route
					body	+ field 2 - example - an example value for the parameter
					body	+ field 3 - type - the parameter type, such as "string", "number", "boolean", "string, optional", "string, required"
					body	+ field 4 - description - information about the parameter
					body	
					body	**parameter example**
					body	
					body	parameter<TAB>country_code<TAB>US<TAB>string<TAB>the country code of interest
					body	
					body	**parameter line relationships**
					body	
					body	parameter lines are added to a parameters array
					body	
					body	**parameters array**
					body	
					body	```json
					body	{"parameters":
					body	  [
					body	    {
					body	      "name" : " field[1],
					body	      "example" : field[2],
					body	      "type" : field[3],
					body	      "description" : field[4]
					body	    }
					body	  ]
					body	}
					body	```
	route	/apitxt/method	method
		method	GET	Get method definition
			line	The method element represents an action that can be performed on a route
			line	
			line	**method line**
			line	
			line	method &lt;TAB> HTTP method &lt;TAB> name &lt;TAB> description
			line	
			line	+ field 1 - HTTP method - the type of action to perform: GET, POST, PUT, DELETE
			line	+ field 2 - name - the name of the action
			line	+ field 3 - description - information about the method
			line	
			line	**method example**
			line	
			line	method &lt;TAB> GET &lt;TAB> Get an example &lt;TAB> This method retrieves an example document
			line	
			line	**method line relationships**
			line	
			line	```
			line	    method
			line	     | - lines
			line	     | - code
			line	     | - requests
			line	     | - responses
			line	```
			line	
			line	**method object**
			line	
			line	```json
			line	{
			line	  "method" : field[1],
			line	  "name" : field[2],
			line	  "description" : field[3],
			line	  "lines" : [],
			line	  "code" : [],
			line	  "dialog" : [
			line	    {
			line	      "request" : {},
			line	      "responses" : []
			line	    }
			line	  ]
			line	}
			line	```
			line	
			request	the method definition
				response	200	text/plain
					body	The method element represents an action that can be performed on a route
					body	
					body	**method line**
					body	
					body	method<TAB>HTTP method<TAB>name<TAB>description
					body	
					body	+ field 1 - HTTP method - the type of action to perform: GET, POST, PUT, DELETE
					body	+ field 2 - name - the name of the action
					body	+ field 3 - description - information about the method
					body	
					body	**method example**
					body	
					body	method<TAB>GET<TAB>Get an example<TAB>This method retrieves an example document
					body	
					body	**method line relationships**
					body	
					body	```
					body	    method
					body	     | - lines
					body	     | - code
					body	     | - requests
					body	     | - responses
					body	```
					body	
					body	**method object**
					body	
					body	```json
					body	{
					body	  "method" : field[1],
					body	  "name" : field[2],
					body	  "description" : field[3],
					body	  "lines" : [],
					body	  "code" : [],
					body	  "dialog" : [
					body	    {
					body	      "request" : {},
					body	      "responses" : []
					body	    }
					body	  ]
					body	}
					body	```
	route	/apitxt/request	request
		method	GET	Get request definition
			line	The request element is associated with a specific method and can be paired with multiple responses.
			line	
			line	**request line**
			line	
			line	request &lt;TAB> name &lt;TAB> type
			line	
			line	+ field 1 - name - uniquely identifies a request
			line	+ field 2 - type - the content type of the request body
			line	
			line	**request example**
			line	
			line	request &lt;TAB> matching text within request body &lt;TAB> plain/text
			line	
			line	**request line relationships**
			line	
			line	```
			line	    request
			line	     | - lines
			line	     | - headers
			line	     | - body
			line	```
			line	
			line	**request object**
			line	
			line	```json
			line	{
			line	  "name" : field[1],
			line	  "type" : field[2],
			line	  "lines" : [],
			line	  "headers" : {},
			line	  "body" : []
			line	}
			line	```
			line	
			request	the request definition
				response	200	text/plain
					body	The request element is associated with a specific method and can be paired with multiple responses.
					body	
					body	**request line**
					body	
					body	request<TAB>name<TAB>type
					body	
					body	+ field 1 - name - uniquely identifies a request
					body	+ field 2 - type - the content type of the request body
					body	
					body	**request example**
					body	
					body	request<TAB>matching text within request body<TAB>plain/text
					body	
					body	**request line relationships**
					body	
					body	```
					body	    request
					body	     | - lines
					body	     | - headers
					body	     | - body
					body	```
					body	
					body	**request object**
					body	
					body	```json
					body	{
					body	  "name" : field[1],
					body	  "type" : field[2],
					body	  "lines" : [],
					body	  "headers" : {},
					body	  "body" : []
					body	}
					body	```
	route	/apitxt/response	response
		method	GET	Get response definition
			line	The response element is associated with a specific request, or associated with a specific method with an assumed generic request.
			line	
			line	**response line**
			line	
			line	response &lt;TAB> status &lt;TAB> type
			line	
			line	+ field 1 - status - an HTTP response code indicating the status of the request
			line	+ field 2 - type - the content type of the response body
			line	
			line	**response example**
			line	
			line	response &lt;TAB> 200 &lt;TAB> plain/text
			line	
			line	**response line relationships**
			line	
			line	```
			line	    response
			line	     | - lines
			line	     | - headers
			line	     | - body
			line	```
			line	
			line	**response object**
			line	
			line	```json
			line	{
			line	  "status" : field[1],
			line	  "type" : field[2],
			line	  "lines" : [],
			line	  "headers" : {},
			line	  "body" : []
			line	}
			line	```
			line	
			request	the response definition
				response	200	text/plain
					body	The response element is associated with a specific request, or associated with a specific method with an assumed generic request.
					body	
					body	**response line**
					body	
					body	response<TAB>status<TAB>type
					body	
					body	+ field 1 - status - an HTTP response code indicating the status of the request
					body	+ field 2 - type - the content type of the response body
					body	
					body	**response example**
					body	
					body	response<TAB>200<TAB>plain/text
					body	
					body	**response line relationships**
					body	
					body	```
					body	    response
					body	     | - lines
					body	     | - headers
					body	     | - body
					body	```
					body	
					body	**response object**
					body	
					body	```json
					body	{
					body	  "status" : field[1],
					body	  "type" : field[2],
					body	  "lines" : [],
					body	  "headers" : {},
					body	  "body" : []
					body	}
					body	```
	route	/apitxt/header	header
		method	GET	Get header definition
			line	The header element is applied to a preceding route
			line	
			line	**header line**
			line	
			line	header &lt;TAB> name &lt;TAB> value
			line	
			line	+ field 1 - name - the header variable name
			line	+ field 2 - value - the header variable value
			line	
			line	**header example**
			line	
			line	header &lt;TAB> X-Powered-By &lt;TAB> ApiTxt
			line	
			line	**header object**
			line	
			line	```json
			line	{ field[1] : field[2] }
			line	```
			line	
			request	the header definition
				response	200	text/plain
					body	The header element is applied to a preceding request or response
					body	
					body	**header line**
					body	
					body	header<TAB>name<TAB>value
					body	
					body	+ field 1 - name - the header variable name
					body	+ field 2 - value - the header variable value
					body	
					body	**header example**
					body	
					body	header<TAB>X-Powered-By<TAB>ApiTxt
					body	
					body	**header object**
					body	
					body	```json
					body	{ field[1] : field[2] }
					body	```
	route	/apitxt/body	body
		method	GET	Get body definition
			line	The body element adds contents to a preceding request or response.
			line	
			line	The text of the body is everything after the string "body &lt;TAB>".
			request	the body definition
				response	200	text/plain
					body	The body element adds contents to a preceding request or response.
					body	
					body	The text of the body is everything after the string "body <tab>"
	route	/apitxt/line	line
		method	GET	Get line definition
			line	The line element adds additional text to frame elements.
			line	
			line	For the root, group, route, method, request, and response, the lines add details to an element.
			line	
			line	The text of the line is everything after the string "line &lt;TAB>".
			request	the line definition
				response	200	text/plain
					body	The line element adds additional text to frame elements.
					body	
					body	For the root, group, route, method, request, and response, the lines add details to an element.
					body	
					body	The text of the line is everything after the string "line <tab>".
	route	/apitxt/code	code
		method	GET	Get code definition
			line	The code element adds functionality to the method element.
			line	
			line	The code element contains programming text.  ApiTxt comes integrated with the PHP project the Slim Framework v2.  The conversion to working PHP adds boilerplate details for routes and method, with named parameters and query parameters available as functional variables.
			line	
			line	The text of the code is everything after the string "code &lt;TAB>".
			request	the code definition
				response	200	text/plain
					body	The code element adds functionality to the method element.
					body	
					body	The code element contains programming text.  ApiTxt comes integrated with the PHP project the Slim Framework v2.  The conversion to working PHP adds boilerplate details for routes and method, with named parameters and query parameters available as functional variables.
					body	
					body	The text of the code is everything after the string "code <tab>".