{% from 'docutil.html' import code, avro_field, avro_link %} {%- macro parameters(params) -%} {% if params %}?
{% for param in params %}{% if not loop.first %}
&{% endif %}{{ param.name }}=...{% endfor %}{% else %}/{% endif %} {%- endmacro -%} {%- macro parameter_table(params) -%} {% for param in params %} {% endfor %}
Parameter Type Default Description
{{ param.name }} {{ avro_field(param.type) }} {{ code(param.default) }} {% if not param.has_key('default') %}REQUIRED {% endif %}{{ param.doc|join|safe }}
{%- endmacro -%} {{ rootSpec.name }} API Documentation Home

The {{ rootSpec.name }} API

View json source

TODO: Should support custom docs for standard operations

{% macro document(spec, basePath) %} {% set path = basePath + '/' + spec.name %} {% set entity = spec.entity if spec.entity else spec.collection %}

{{ code(spec.name) }}

{{ spec.doc|join|safe }}

{% if spec.identifier %}
Identifier Name {{ code(spec.identifier.name) }}
Type {{ avro_field(spec.identifier.type) }}
Notes {{ spec.identifier.doc|join|safe }}

{% endif %} {% if spec.supports %} {% for method_name in spec.supports %} {% if spec.supports[method_name] and spec.supports[method_name] != spec.supports|attr(method_name) %} {% set method = spec.supports[method_name] %} {% else %} {% set method = {} %} {% endif %} {% if not spec.entity %} {% if method_name == 'get_all' %} {% elif method_name == 'count' %} {% elif method_name == 'get' %} {% elif method_name == 'create' %} {% elif method_name == 'update' %} {% elif method_name == 'delete' %} {% elif method_name == 'batch_get' %} {% elif method_name == 'batch_create' %} {% elif method_name == 'batch_update' %} {% elif method_name == 'batch_delete' %} {% endif %} {% else %} {% if method_name == 'get' %} {% elif method_name == 'create' %} {% elif method_name == 'update' %} {% elif method_name == 'delete' %} {% endif %} {% endif %} {% endfor %}
HTTP method Path Body Response Notes
GET {{ path }}/   {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% else %} A collection of {{ avro_link(entity) }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Gets all the {{ avro_link(entity) }}s in the {{ code(spec.name) }} collection. {% endif %} GET {{ path }}/count/   {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% else %} {{ code('int') }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} The count of {{ code(spec.name) }}. {% endif %} GET {{ path }}/[{{ spec.identifier.name }}]/   {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% else %} {{ avro_link(entity) }} identified by {{ code(spec.identifier.name) }} {% endif %} {{ method.doc|join|safe }} POST {{ path }}/ {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% elif entity %} {{ avro_link(entity) }} to create {% endif %} {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% elif entity %} URI to pointing to new {{ avro_link(entity) }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Creates a new {{ avro_link(entity) }}. {% endif %} PUT {{ path }}/[{{ spec.identifier.name }}]/ {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% elif entity %} A sparse {{ avro_link(entity) }} (only set fields will be updated) {% endif %} {{ method.response_doc|join|safe }} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Applies a partial update to the {{ avro_link(entity) }}. TODO: This kind of breaks the semantics of standard PUT, which should replace the object {% endif %} DELETE {{ path }}/[{{ spec.identifier.name }}]/   {{ method.response_doc|join|safe }} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Deletes the {{ avro_link(entity) }} identified by {{ code(spec.identifier.name) }}. {% endif %} GET {{ path }}?{{ spec.identifier.name }}=[{{ spec.identifier.name }}1]&{{ spec.identifier.name }}=[{{ spec.identifier.name }}2]&...   {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% else %} An array of {{ avro_link(entity) }} matching the given {{ code(spec.identifier.name + 's') }} {% endif %} {{ method.doc|join|safe }} POST {{ path }}?multi= {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% elif entity %} An array of {{ avro_link(entity) }} to create {% endif %} {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% elif entity %} An array of URIs pointing to the new {{ avro_link(entity) }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Batch creation of {{ avro_link(entity) }}. {% endif %} PUT {{ path }}?multi= {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% elif entity %} An array of sparse {{ avro_link(entity) }} (only set fields will be updated). The {{ code(spec.identifier.name + 's') }} MUST be set on each {{ avro_link(entity) }} passed in. {% endif %} {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Batch partial updates to {{ avro_link(entity) }} identified by {{ code(spec.identifier.name + 's') }} in the request body. TODO: This kind of breaks the semantics of standard PUT, which should replace the collection {% endif %} DELETE {{ path }}?{{ spec.identifier.name }}=[{{ spec.identifier.name }}1]&{{ spec.identifier.name }}=[{{ spec.identifier.name }}2]&...   {% if 'response_doc' in method %} {{ method.response_doc|join|safe }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Batch delete of the {{ avro_link(entity) }} identified by the given {{ code(spec.identifier.name + 's') }} {% endif %}
GET {{ path }}/   {% if 'response_doc' in method %} {{ method.response|join|safe }} {% else %} {{ avro_link(entity) }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Gets the {{ code(spec.name) }} {{ avro_link(entity) }} {% endif %} POST {{ path }}/ {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% else %} {{ avro_link(entity) }} to create {% endif %} {% if 'response_doc' in method %} {{ method.response|join|safe }} {% else %} URI to pointing to the new {{ avro_link(entity) }} {% endif %} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Creates a new {{ code(spec.name) }} {{ avro_link(entity) }}. TODO: Is it an error if you try to create one when one already exists? Does this even get added to the parent collection? {% endif %} PUT {{ path }}/ {% if 'body_doc' in method %} {{ method.body_doc|join|safe }} {% else %} A sparse {{ avro_link(entity) }} (only set fields will be updated) {% endif %} {{ method.response|join|safe }} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Applies a partial update to the {{ code(spec.name) }} {{ avro_link(entity) }}. TODO: This kind of breaks the semantics of standard PUT, which should replace the object {% endif %} DELETE {{ path }}/   {{ method.response|join|safe }} {% if 'doc' in method %} {{ method.doc|join|safe }} {% else %} Deletes the {{ code(spec.name) }} {{ avro_link(entity) }}. {% endif %}
{% endif %} {# spec.supports #} {% if spec.find %} {% for method in spec.find %} {% if method.doc %}

{{ method.doc|join|safe }}

{% endif %} {% for param in method.parameters %} {% if not loop.first %}{% endif %} {% else %} {% if not loop.first %}{% endif %} {% endfor %}
HTTP method Path Response Parameter Type Default Description
GET {{ path }}{{ parameters(method.parameters) }}{% if method.name %}
&s={{ method.name }}{% endif %}
A collection of {{ avro_link(entity) }}
{{ param.name }} {{ avro_field(param.type) }} {{ code(param.default) }} {% if not param.has_key('default') %}REQUIRED {% endif %}{{ param.doc|join|safe }}
       
{% endfor %} {% endif %} {% if spec.namespaced %} {% for resource in spec.namespaced %} {{ document(resource, path) }} {% endfor %} {% endif %} {% if spec.scoped %} {% for resource in spec.scoped %} {{ document(resource, path + '/[' + spec.identifier.name + ']') }} {% endfor %} {% endif %} {% if spec.custom %}

Custom methods

These are non-standard methods that make state changes on the server.

{% for method in spec.custom %} {% endfor %}
HTTP method Path Body Response Description
POST {{ path }}/{{ method.name }}/ {% if method.body %} {{ parameter_table(method.body) }} {% endif %} An object of type: {{ code(method.response) }} {{ method.doc|join|safe }}
{% endif %} {% endmacro %} {{ document(rootSpec, '') }}