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 -%}
{% if "alias_for_path" in endpoint -%}
``{{endpoint.path}}`` is an alias for `{{endpoint.alias_for_path}}`_.

.. _`{{endpoint.alias_for_path}}`: #{{endpoint.alias_link}}
{% else -%}

{{endpoint.desc | wrap(80)}}

{{":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.example.responses|length > 0 -%}
Response{{"s" if endpoint.example.responses|length > 1 else "" }}:

{% endif -%}

{% for res in endpoint.example.responses -%}

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

{{res["description"]}}

Example

.. code:: json

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

{% endfor %}
{% endif -%}