Skip to main content

Create API specifications and documentation using Python

Project description

Pactum

The HTTP-API specification sketchbook for pythonistas

Circle CI

pip install pactum

With Pactum you can specify HTTP-APIs using pure python.

Pactum is easy to use, easy to extend and easy to contribute:

Easy to use

The only requirements to start writing an API specification with pactum is pactum package itself and some knowledge of python.

import pactum

class MyAPI(pactum.API):
    name = 'My API'
    versions = [...]

Easy to extend

Using the visitor pattern you can create exporters and extensions for any format or service you want.

Take a look at pactum/exporters/openapi.py.

Architecture

Always keep this diagram in mind when defining your APIs.

Tutorial

Create a file called specs.py and start defining your API.

You can define a Resource object for your API.

from pactum import Action, API, Resource, Response, Version
from pactum import fields, verbs

class Order(Resource):
    fields = [
        fields.IntegerField(name='code', required=True),
        fields.TimestampField(name='created_at'),
        fields.StringField(name='item')
    ]
resource = Order()

error_resource = Resource(
    name = 'ErrorResource'
    fields = [fields.StringField(name='error', required=False)]
)

You can define any element of your specification by calling it directly as in error_resource or by class definition as in MyResource and then calling it.

List resources are definitions of lists of the same resource.

list_order_resource = ListResource(resource=resource)

You can define Response objects with status, description(optional) a header(optional) and a Resource/ListResource object as body (optionally)...

list_response = Response(
    status=200, description='Here is your orders list.', body=list_resource
)

detail_response = Response(
    status=200, description='Here is your order.', body=resource
)

error_response = Response(status=404, resource=error_resource, headers=[('Content-type': 'application-json')])

... and Request objects with verb, description, header(optional) and a Resource/ListResource object as payload.

get_request = Request(verb=verbs.GET)

An Action groups your request and a list of responses for a specified action passed in the description parameter.

list_action = Action(
    description='Returns a list of resources.',
    request=get_request,
    responses=[error_response, list_response]
)

detail_action = Action(
    description='Returns a resource based on its code.',
    request=get_request,
    responses=[error_response, detail_response]
)

The Action object, as all other elements in Pactum, receive a description string that sets the .__doc__ attribute and can be the docstring of the class if the object is defined by class definition.

A route can have a list of actions in an HTTP path.

class OrderListRoute(Route):
    path = '/orders'
    actions = [list_action]

list_route = OrderListRoute()

detail_route = OrderRoute(path='/orders/{code}', actions=detail_action)

Your routes can be grouped in API versions.

class V1(Version):
    name = 'V1'
    routes = [list_route, detail_route]

v1 = V1()

Then you can define your API. ;)

class OrdersAPI(API):
    name = 'Orders API'
    versions = [v1]

api = OrdersAPI()

Be happy and ready to export your specification to any format you want.

Exporting to openapi specs.

Pactum has a command that exports your specification to OpenAPI. You can call it by using:

pactum-openapi <spec_file.py> <output_file> [--format=<json or yaml>]

Road to version 1.

  • Test elements .accept(visitor) methods.
  • Support for version selectors (Versions should be specified on HTTP header, path, or custom fields)
  • Stabilize the way we work with path parameters.
  • Support for Authorization and Authentication Specifications.
  • Support for extensions.
  • Behaviors

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pactum-0.2.0.tar.gz (16.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page