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

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

``{{endpoint.method}} {{endpoint.path}}``
{{(5 + (endpoint.path | length) + (endpoint.method | length)) * title_kind}}
{% if "deprecated" in endpoint and endpoint.deprecated -%}
.. WARNING::
  This API is deprecated and will be removed from a future release.

{% endif -%}

{{endpoint.desc}}

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

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 -%}
{{"``"+table.title+"``" if table.title else "" }}
{{ tables.paramtable(table.rows) }}
{% endfor -%}
{% endif -%}

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

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

{% for table in endpoint.res_tables -%}
{{"``"+table.title+"``" if table.title else "" }}

{{ tables.paramtable(table.rows) }}

{% endfor %}
{% endif -%}

Example request:

.. code:: http

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

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

{% endif -%}

{% for res in endpoint.responses -%}

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

{{res["description"]}}

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

Example

.. code:: json

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

{% endif -%}

{% endfor %}