matrix-spec-proposals/scripts/templating/matrix_templates/templates/http-api.tmpl

{% import 'tables.tmpl' as tables -%}

{% if "deprecated" in endpoint and endpoint.deprecated -%}
Deprecated: ``{{endpoint.method}} {{endpoint.path}}``
{{(17 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}}

.. WARNING::
  This API is deprecated and will be removed from a future release.

{% else %}
``{{endpoint.method}} {{endpoint.path}}``
{{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}}
{% endif -%}

{{endpoint.desc}}

{{":Rate-limited: Yes." if endpoint.rate_limited else ":Rate-limited: No." }}
{{":Requires auth: Yes." if endpoint.requires_auth else ":Requires auth: No." }}

.. class:: httpheaders

  Request format:

{% if (endpoint.req_param_by_loc | length) %}
{{ tables.split_paramtable(endpoint.req_param_by_loc) }}
{% if (endpoint.req_body_tables) %}
{% for table in endpoint.req_body_tables -%}
{{ tables.paramtable(table.rows, caption=(table.title or "")) }}

{% endfor -%}
{% endif -%}

{% else %}
`No parameters`
{% endif %}

{% if endpoint.res_headers is not none -%}

.. class:: httpheaders

  Response headers:

{{ tables.paramtable(endpoint.res_headers.rows) }}
{% endif -%}

{% if endpoint.res_tables|length > 0 -%}

.. class:: httpheaders

  Response format:

{% for table in endpoint.res_tables -%}

{{ tables.paramtable(table.rows, caption=(table.title or "")) }}


{% endfor %}
{% endif -%}

.. class:: httpheaders

  Example request:

.. code:: http

  {{endpoint.example.req | indent_block(2)}}

{% if endpoint.responses|length > 0 -%}

.. class:: httpheaders

  Response{{"s" if endpoint.responses|length > 1 else "" }}:

{% endif -%}

{% for res in endpoint.responses -%}

**Status code {{res["code"]}}:**

{{res["description"]}}

{% if res["example"] -%}

.. class:: httpheaders

  Example

.. code:: json

  {{res["example"] | indent_block(2)}}

{% endif -%}

{% endfor %}