Sphinx directive for RESTful HTTP API examples

sphinxcontrib-httpexample is a Sphinx domain extension for describing RESTful HTTP APIs in detail. It enhances sphinxcontrib-httpdomain with a simple call example directive. The directive provided by this extension generates RESTful HTTP API call examples for different HTTP clients from a single HTTP request example.

The audience for this extension are developers and technical writers documenting their RESTful HTTP APIs. This extension was originally developed for documenting plone.restapi.

Configuration

The URL scheme, either http or https, used in the generated examples can be configured with the httpexample_scheme configuration variable. It defaults to http.

# conf.py
httpexample_scheme = "https"

Syntax

There are two syntaxes, one each for inline and external sources.

The following example is of inline sources.

..  http:example:: space separated list of tools
    A required inline source of a raw plain text HTTP request example.
    This is required.


    An optional inline source of a raw plain text HTTP response example.
    If present, it must be separated from the request by two blank lines.
    It must begin with either ``HTTP/VERSION_NUMBER`` or ``HTTP ``.

The following example is of external sources.

..  http:example:: space separated list of tools
    :request: ../relative/path/to/plaintext/request/file
    :response: ../relative/path/to/plaintext/response/file

To display the response outside of the tabbed interface, then don't include it in the http:example directive, but instead list it separately.

For inline sources, use code-block with the http-response lexer.

..  http:example:: space separated list of tools
    A required inline source of a raw plain text HTTP request example.
    This is required.

..  code-block:: http
    An optional inline source of a raw plain text HTTP response example.

For external sources, use literalinclude with either the http or http-response lexer.

..  http:example:: space separated list of tools
    :request: ../relative/path/to/plaintext/request/file

..  literalinclude:: ../relative/path/to/plaintext/response/file
    :language: http

Example

..  http:example:: curl wget httpie requests urllib3 plone-client

    POST /Plone/folder HTTP/1.1
    Host: localhost:8080
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic YWRtaW46YWRtaW4=


    HTTP 200 OK
    Content-Type: application/json

    {
        "@type": "Document",
        "title": "My Document"
    }

Rendering

http

POST /Plone/folder HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

curl

curl -i -X POST http://localhost:8080/Plone/folder -H "Accept: application/json" -H "Content-Type: application/json" --user admin:admin

wget

wget -S -O- http://localhost:8080/Plone/folder --header="Accept: application/json" --header="Content-Type: application/json" --auth-no-challenge --user=admin --password=admin

httpie

http POST http://localhost:8080/Plone/folder Accept:application/json Content-Type:application/json -a admin:admin

requests

requests.post('http://localhost:8080/Plone/folder', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, auth=('admin', 'admin'))

urllib3

import urllib3
import json
from urllib3.util import make_headers
http = urllib3.PoolManager()
headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
headers.update(make_headers(basic_auth='admin:admin'))
r = http.request('POST', 'http://localhost:8080/Plone/folder', headers=headers)

@plone/client

import PloneClient from '@plone/client';

const cli = PloneClient.initialize({apiPath: 'http://localhost:8080/Plone'});

cli.login({username: 'admin', password: 'admin'});

cli.createContent({
  path: '/folder',
  data: null,
});

response

HTTP 200 OK
Content-Type: application/json

{
    "@type": "Document",
    "title": "My Document"
}

Sphinx directive for RESTful HTTP API examples

Configuration

Syntax

Example

Rendering

Compatibility with other tab libraries

sphinx-inline-tabs 

sphinx-design 

Custom builders

Supported tools

Contents

Sphinx directive for RESTful HTTP API examples

Configuration

Syntax

Example

Rendering

Compatibility with other tab libraries

sphinx-inline-tabs

sphinx-design

Custom builders

Supported tools

Contents

sphinx-inline-tabs 

sphinx-design 