.. _administrator_restfulsimplifiedrelatedstudent_details_search: ============================================================================= GET /administrator/restfulsimplifiedrelatedstudent/ ============================================================================= Search for related students. The underlying data model searched is defined in :class:`devilry.apps.core.models.relateduser.RelatedStudent`. The :ref:`simplified` that the server forwards this request to is :meth:`devilry.apps.administrator.simplified.simplifiedrelatedstudent.SimplifiedRelatedStudent.search`. The request parameters (below) all modify the result of the search. They are applied in the following order: 1. The ``query`` is executed. 2. The result of the query is filtered through the ``filters``. 3. The result of the filtering is ordered as specified in ``orderby``. 4. The result of the ordering is limited by ``start`` and ``limit``. ************************** Request ************************** Request example ############### .. code-block:: javascript GET /administrator/restfulsimplifiedrelatedstudent/ { query: 'a query string', filters: [{field:"candidate_id", comp:"exact", value:"My example value"}, {field:"id", comp:"exact", value:15}, {field:"period", comp:"exact", value:15}], orderby: ["id", "-period", "user", "tags", "user__username", "user__devilryuserprofile__full_name", "user__email", "candidate_id"], start: 10, limit: 100 } Optional request parameters ########################### Optional request parameters are encoded as a JSON object and sent as the request body as shown in the example above. query ----- A string to search for. If this is empty or not given, all related students that the authenticated user has access to is returned. If the string is not empty, the ``query``-string is split on whitespace, resulting in a list of words. Every *word* in the list is searched for *case-insensitive* matches within the following fields: user__username Actual location of the field: :class:`django.contrib.auth.models.User` About the field: Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters Type String user__devilryuserprofile__full_name Actual location of the field: :class:`devilry.apps.core.models.DevilryUserProfile` About the field: List of many values. Type List of strings candidate_id Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: If a candidate has the same Candidate ID for all or many assignments in a semester, this field can be set to simplify setting candidate IDs on each assignment. Type String filters ------- Filters can be used to perform complex queries. The ``filters`` parameter is a list of filters, where each filter is a map with the following entries: field A field name. comp A comparison operator. value The value to filter on. Example: .. code-block:: javascript [{field:"candidate_id", comp:"exact", value:"My example value"}, {field:"id", comp:"exact", value:15}, {field:"period", comp:"exact", value:15}] related students can be filtered on the following *fields*: candidate_id Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: If a candidate has the same Candidate ID for all or many assignments in a semester, this field can be set to simplify setting candidate IDs on each assignment. Type String Supported comparison operators: ``startswith``, ``contains``, ``>=``, ``<=``, ``icontains``, ``iexact``, ``endswith``, ``exact``, ``<``, ``>``. id Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: Autogenerated identifier. Type Integer Supported comparison operators: ``exact``. period Actual location of the field: :class:`devilry.apps.core.models.Period` About the field: Autogenerated identifier. Type Integer Supported comparison operators: ``exact``. user Actual location of the field: :class:`django.contrib.auth.models.User` About the field: Autogenerated identifier. Type Integer Supported comparison operators: ``exact``. exact_number_of_results ----------------------- If given, this must be a positive integer (including 0), which specifies the exact number of expected results. This enables searches that you know should fail if they do not get this exact number of results, such as filtering for a User by unique username instead of its numeric ID (where you should expect exactly one result). orderby ------- List of fieldnames. Order the result by these fields. Fieldnames can be prefixed by ``'-'`` for descending ordering. start ----- After query, filters and orderby have been executed, the result is limited to the values from *start* to *start+limit*. Start defalts to ``0``. limit ----- Limit results to this number of items. Defaults to ``50``. ********************* Response ********************* On success ########## Example ------------------------ *note that the is wrong in the example. The id is always unique. However, the example is generated from a non-varying dataset.* .. code-block:: javascript 200 OK { total: 20, items: [ { id: 15, period: 15, user: 15, tags: "myvalue", user__username: "My example value", user__devilryuserprofile__full_name: ["this", "is", "an", "example"], user__email: "My example value", candidate_id: "My example value" }, { id: 15, period: 15, user: 15, tags: "myvalue", user__username: "My example value", user__devilryuserprofile__full_name: ["this", "is", "an", "example"], user__email: "My example value", candidate_id: "My example value" }, ... ] } Success response details ------------------------ Responds with HTTP code *200* and a *JSON encoded* dict containing the list of results and the *total* number of items found before applying ``limit`` and ``start``. Each result in the list is a JSON object where the *key* is a fieldname and the associated value is the *value* for that field. The result always contains the following fields: id Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: Autogenerated identifier. Type Integer period Actual location of the field: :class:`devilry.apps.core.models.Period` About the field: Autogenerated identifier. Type Integer user Actual location of the field: :class:`django.contrib.auth.models.User` About the field: Autogenerated identifier. Type Integer tags Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: Comma-separated list of tags. Each tag is a word with the following letters allowed: a-z and 0-9. Each word is separated by a comma, and no whitespace. Type String user__username Actual location of the field: :class:`django.contrib.auth.models.User` About the field: Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ characters Type String user__devilryuserprofile__full_name Actual location of the field: :class:`devilry.apps.core.models.DevilryUserProfile` About the field: List of many values. Type List of strings user__email Actual location of the field: :class:`django.contrib.auth.models.User` About the field: Type String candidate_id Actual location of the field: :class:`devilry.apps.core.models.relateduser.RelatedStudent` About the field: If a candidate has the same Candidate ID for all or many assignments in a semester, this field can be set to simplify setting candidate IDs on each assignment. Type String On error ######## On errors, we respond with one of the :ref:`restful_api_error_statuscodes`.