Define HTTP APIs easily.
Project description
strut
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 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 tests, that could automatically generate testing.
strut gherkin definition.http
Code Generation
By compiling down to Swagger code, server code can be generated. See an example implementation on editor.swagger.io/ under the "Generate Server" tab.
strut 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) 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.
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,
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.