<commit_before>=======
The API
=======

Responses are communicated in `JavaScript Object Notation (javascript) <http://javascript.org>`__. Each endpoint returns a list of ``objects``. A few useful book-keeping items are also included in each response.

.. code:: javascript

    {
        "num_results": <int>,
        "objects": [
            {
                <key>: <value>,
                <key>: <value>,
                ...
                <key>: <value>
            },
            { <response object 2> },
            ...
            { <response object N> }
        ],
        "page": <int>,
        "total_pages": <int>
    }

The exception is :ref:`api/courses/\<course> <api-courses>`, which returns a single object (not a list), and no book-keeping items.

It is possible for zero ``<response object>``\ s to be returned.

Pagination
~~~~~~~~~~

Each response includes:
 * ``page`` := page number returned
 * ``total_pages`` := total number of pages

To get the nth page, append ``?page=<n>`` to any endpoint::

 GET /api/courses-min?page=2

If you are using a search query, append the page number with ``&``::

 GET /api/courses-min?q=<search_query>&page=2

Search queries
~~~~~~~~~~~~~~

`Search queries <http://flask-restless.readthedocs.org/en/latest/searchformat.html#searchformat>`__ are used to restrict an endpoint's output. This is useful both for performance and semantic reasons.

Format is::

 /api/<endpoint>?q={"filters":[{"name":<attribute_name>,"op":<comparison>,"val":<attribute_value>},{ ... },...]}

Examples:

 * Get courses for a certain institution and a certain term::

	 GET /api/courses-min?q={"filters":[{"name":"institution","op":"equals","val":"ualberta"},{"name":"term","op":"equal","val":"1490"}]}

 * Get terms for a certain institution::

 	 GET /api/terms?q={"filters":[{"name":"institution","op":"equals","val":"ualberta"}]}


.. _api-institutions

api/institutions
~~~~~~~~~~~~~~~~

Retrieve a list of available institutions. Each institution contains all available information.

Request
'''''''

::

 GET localhost:5000/api/institutions<commit_msg>docs(api): add search query operators<commit_after>=======
The API
=======

Responses are communicated in `JavaScript Object Notation (javascript) <http://javascript.org>`__. Each endpoint returns a list of ``objects``. A few useful book-keeping items are also included in each response.

.. code:: javascript

    {
        "num_results": <int>,
        "objects": [
            {
                <key>: <value>,
                <key>: <value>,
                ...
                <key>: <value>
            },
            { <response object 2> },
            ...
            { <response object N> }
        ],
        "page": <int>,
        "total_pages": <int>
    }

The exception is :ref:`api/courses/\<course> <api-courses>`, which returns a single object (not a list), and no book-keeping items.

It is possible for zero ``<response object>``\ s to be returned.

Pagination
~~~~~~~~~~

Each response includes:
 * ``page`` := page number returned
 * ``total_pages`` := total number of pages

To get the nth page, append ``?page=<n>`` to any endpoint::

 GET /api/courses-min?page=2

If you are using a search query, append the page number with ``&``::

 GET /api/courses-min?q=<search_query>&page=2

Search queries
~~~~~~~~~~~~~~

`Search queries <http://flask-restless.readthedocs.org/en/latest/searchformat.html#searchformat>`__ are used to restrict an endpoint's output. This is useful both for performance and semantic reasons.

Format is::

 /api/<endpoint>?q={"filters":[{"name":<attribute_name>,"op":<comparison>,"val":<attribute_value>},{ ... },...]}

Examples:

 * Get courses for a certain institution and a certain term::

	 GET /api/courses-min?q={"filters":[{"name":"institution","op":"equals","val":"ualberta"},{"name":"term","op":"equal","val":"1490"}]}

 * Get terms for a certain institution::

 	 GET /api/terms?q={"filters":[{"name":"institution","op":"equals","val":"ualberta"}]}

Available operators `listed here <http://flask-restless.readthedocs.org/en/latest/searchformat.html#operators>`__. As of this writing, they are::

    ==, eq, equals, equals_to
    !=, neq, does_not_equal, not_equal_to
    >, gt, <, lt
    >=, ge, gte, geq, <=, le, lte, leq
    in, not_in
    is_null, is_not_null
    like
    has
    any

.. _api-institutions

api/institutions
~~~~~~~~~~~~~~~~

Retrieve a list of available institutions. Each institution contains all available information.

Request
'''''''

::

 GET localhost:5000/api/institutions
{'fraction_non_alphanumeric': 0.17830478700043917, 'fraction_numerical': 0.004830917874396135, 'mean_word_length': 3.329847908745247, 'pattern_counts': {'":': 38, '<': 50, '<?xml version=': 0, '>': 50, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '571862', 'n_tokens_mistral': 1414, 'n_tokens_neox': 1331, 'n_words': 395}