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