Metadata-Version: 2.1
Name: strut
Version: 1.0.1
Summary: Define HTTP APIs easily.
Home-page: https://github.com/trevorgrayson/strut
Author: trevor grayson
Author-email: trevor@ipsumllc.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/markdown

# struct

Using HTTP formatting standards to simplify defining web APIs.

The Swagger/OpenAPI specifications are generally ubiquitous and extremely useful.  The 
difficulty comes in when having to remember the fieldnames exactly, or how the document
is structured.  Required fields lead to a lot of noise when compiling them.

It is the purpose of this specification to make defining HTTP endpoints much easier by 
making a more intuitive entry system.  By minimizing format and structure, and by leveraging
the HTTP standard (which may already be known by the developer) it may be quicker and easier
to define APIs.


## Features

### Documentation

By generating [Swagger](https://swagger.io/) yaml/json this project can tap into a rich
community of GUI definitions.

To convert a `.http` file into a swagger document:

```
# yaml
./strut swagger filename.http

# json 
./strut swagger-json filename.http

```

### Testing

This format should lead to be able to infer standard [Gherkin Syntax](https://docs.cucumber.io/gherkin/)
tests, that could automatically generate testing.

```
./struct gherkin definition.http
```

### Code Generation

By compiling down to Swagger code, server code can be generated.  See an example implementation on 
[editor.swagger.io/](http://editor.swagger.io/) under the "Generate Server" tab.

```
./struct swagger definition.http
```

### Web Scripting

`http` files can describe a procedural list of requests to make to a webserver. 
This can be used to script requests to a service, potentially multiple services 
in future iterations.


## Creating Definitions

In order to get use out of this library there are several ways of inputing definitions easily.

### `.http` Files

`.http` files are composed of a collection of HTTP Messages, which can be used 
to describe a service.  Standard HTTP Messages (as defined by 
[rfc2616](https://tools.ietf.org/html/rfc2616)) with each separated by 
?double newline? characters (in the same way as headers and bodies are 
separated), that file can be read in as a `list` of `HttpRequest` objects.

The simplest definition can be acheived with `\n\n` separated [Http Message Request lines](https://tools.ietf.org/html/rfc2616#section-4).

```
GET /kittens

GET /dogs
Content-Type: application/json

```

```
from parser import HttpRequest

requests = HttpRequest.parse_file("filename.http")
```

### Spec Aggregation as a Service

By running the `./strut-server` script locally, you can use a web browser, curl, [Postman](https://www.getpostman.com/), 
or any other HTTP client to hit the service, and easily accumulate a specification.  

This can be saved to a `.http` formatted file for reusability.

An example of this technique could be the following:

```
pip install strut
./strut-server &
> serving at port 4110

curl http://localhost:4110/kittens/
curl http://localhost:4110/dogs/
curl -XPOST http://localhost:4110/kittens/
```

This would generate the following swagger specification:

```

info:
  description: ''
  title: Generated by Strut
  version: 1.0.0
openapi: 3.0.0
paths:
  /dogs:
    get:
      description: ''
      responses:
        '200':
          description: ''
  /kittens:
    get:
      description: ''
      responses:
        '200':
          description: ''
    post:
      description: ''
      responses:
        '200':
          description: ''

```

## Project Life Cycle

### Testing the Project

```
pytest
```

### Parsing and Rendering


