Sphinx directive for RESTful HTTP API examples

sphinxcontrib-httpexample enhances sphinxcontrib-httpdomain, a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new 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 writes documenting their RESTful HTTP APIs. This extension has originally been 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']})

  • Compatible with other 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: