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 tools 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

.. http:example:: space separated list of tools
    :request: ../optional/rel/path/to/plaintext/request
    :response: ../optional/rel/path/to/plaintext/response

    Raw plaintext HTTP request example, which is
    required only when ``:request:`` is not specified.

Example

.. http:example:: curl wget httpie python-requests

    GET /Plone/front-page HTTP/1.1
    Host: localhost:8080
    Accept: application/json
    Authorization: Basic YWRtaW46YWRtaW4=

Rendering

http

GET /plone/folder/my-document?expand=breadcrumbs%2Cnavigation HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://localhost:8080/plone/folder/my-document?expand=breadcrumbs%2Cnavigation' -H "Accept: application/json" --user admin:secret

wget

wget -S -O- 'http://localhost:8080/plone/folder/my-document?expand=breadcrumbs%2Cnavigation' --header="Accept: application/json" --auth-no-challenge --user=admin --password=secret

httpie

http 'http://localhost:8080/plone/folder/my-document?expand=breadcrumbs%2Cnavigation' Accept:application/json -a admin:secret

python-requests

requests.get('http://localhost:8080/plone/folder/my-document?expand=breadcrumbs%2Cnavigation', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

import PloneClient from '@plone/client';
const cli = PloneClient.initialize({apiPath: 'http://nohost/plone'});
const { data, status } = cli.getContent({path: '/plone/folder/my-document', expanders: ['breadcrumbs', 'navigation']})

Compatibility with other tab libraries

sphinxcontrib-httpexample is compatible with the following tab libraries.

sphinx-inline-tabs

GET /Plone/front-page HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=

curl -i -X GET http://localhost:8080/Plone/front-page -H "Accept: application/json" --user admin:admin

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

http http://localhost:8080/Plone/front-page Accept:application/json -a admin:admin

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/Plone/front-page",
  "@type": "Document",
  "UID": "1f699ffa110e45afb1ba502f75f7ec33",
  "allow_discussion": null,
  "changeNote": "",
  "contributors": [],
  "created": "2016-01-21T01:14:48+00:00",
  "creators": [
    "test_user_1_",
    "admin"
  ],
  "description": "Congratulations! You have successfully installed Plone.",
  "effective": null,
  "exclude_from_nav": false,
  "expires": null,
  "id": "front-page",
  "language": "",
  "modified": "2016-01-21T01:24:11+00:00",
  "parent": {
    "@id": "http://localhost:8080/Plone",
    "@type": "Plone Site",
    "description": "",
    "title": "Plone site"
  },
  "relatedItems": [],
  "review_state": "private",
  "rights": "",
  "subjects": [],
  "table_of_contents": null,
  "text": {
    "content-type": "text/plain",
    "data": "If you're seeing this instead of the web site you were expecting, the owner of this web site has just installed Plone. Do not contact the Plone Team or the Plone mailing lists about this.",
    "encoding": "utf-8"
  },
  "title": "Welcome to Plone"
}

sphinx-design

GET /Plone/front-page HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=

curl -i -X GET http://localhost:8080/Plone/front-page -H "Accept: application/json" --user admin:admin

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

http http://localhost:8080/Plone/front-page Accept:application/json -a admin:admin

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/Plone/front-page",
  "@type": "Document",
  "UID": "1f699ffa110e45afb1ba502f75f7ec33",
  "allow_discussion": null,
  "changeNote": "",
  "contributors": [],
  "created": "2016-01-21T01:14:48+00:00",
  "creators": [
    "test_user_1_",
    "admin"
  ],
  "description": "Congratulations! You have successfully installed Plone.",
  "effective": null,
  "exclude_from_nav": false,
  "expires": null,
  "id": "front-page",
  "language": "",
  "modified": "2016-01-21T01:24:11+00:00",
  "parent": {
    "@id": "http://localhost:8080/Plone",
    "@type": "Plone Site",
    "description": "",
    "title": "Plone site"
  },
  "relatedItems": [],
  "review_state": "private",
  "rights": "",
  "subjects": [],
  "table_of_contents": null,
  "text": {
    "content-type": "text/plain",
    "data": "If you're seeing this instead of the web site you were expecting, the owner of this web site has just installed Plone. Do not contact the Plone Team or the Plone mailing lists about this.",
    "encoding": "utf-8"
  },
  "title": "Welcome to Plone"
}

Supported tools

Contents