app.views_api
=============

.. py:module:: app.views_api

.. autoapi-nested-parse::

   API views and routes for the Mail List Shield application.

   This module defines the REST API endpoints for email validation,
   credit balance retrieval, and API key testing.



Attributes
----------

.. autoapisummary::

   app.views_api.api_bp


Functions
---------

.. autoapisummary::

   app.views_api.invalid_api_key_response
   app.views_api.no_api_key_response
   app.views_api.no_json_body_response
   app.views_api.missing_key_in_json_response
   app.views_api.insufficient_credit_response
   app.views_api.validate_request_json
   app.views_api.get_user_from_api_key
   app.views_api.successful_validation_response
   app.views_api.api_test
   app.views_api.get_credit_balance
   app.views_api.validate_single


Module Contents
---------------

.. py:data:: api_bp

.. py:function:: invalid_api_key_response()

   Abort the request with a 403 error for invalid API keys.

   We standardize the error response to avoid leaking information about
   why the API key is invalid.


.. py:function:: no_api_key_response()

   Abort the request with a 401 error for missing API keys.


.. py:function:: no_json_body_response()

   Abort the request with a 415 Unsupported Media Type error for missing JSON body.


.. py:function:: missing_key_in_json_response(key_name)

   Abort the request with a 400 Bad Request error for missing keys in JSON body.

   :param key_name: The name of the missing key in the JSON payload.


.. py:function:: insufficient_credit_response()

   Abort the request with a 402 Payment Required error for insufficient credits.


.. py:function:: validate_request_json(request)

   Validate that the request has JSON content type and a JSON body.

   :param request: The Flask request object.

   .. note:: Aborts the request with appropriate error responses if validation fails.


.. py:function:: get_user_from_api_key(request)

   Fetch the user associated with the provided API key.

   :param request: The Flask request object containing the x-api-key header.

   :returns: The user object associated with the API key.
   :rtype: Users

   .. note::

      Aborts with appropriate error responses if the API key is
      missing, invalid, or not associated with a user.


.. py:function:: successful_validation_response(result)

   Return a standardized successful validation response.

   :param result: The validation result dictionary.

   :returns:

             JSON response with validation results. If single_level_response
                 is requested, returns just the result dict. Otherwise, wraps it
                 with status and message.
   :rtype: Response


.. py:function:: api_test()

   A test API endpoint that requires an API key.

   This endpoint forgives requests without their content-type
   set to application/json, because it doesn't read your request body.

   :returns:

             For GET requests, returns a 405 error message.
                 For POST requests, returns a success message with the user's name.
   :rtype: Response


.. py:function:: get_credit_balance()

   The API endpoint to get the user's credit balance.

   This endpoint forgives requests without their content-type
   set to application/json, because it doesn't read your request body.

   :returns: JSON response containing status, message, and credit balance.
   :rtype: dict


.. py:function:: validate_single()

   The API endpoint to validate a single email address.

   This endpoint requires the request content-type to be application/json
   and a JSON body with an "email" key.

   Optionally, the request JSON can include a boolean key "single_level_response".
   If set to true, the API will return the validation result in a single-level dictionary.
   Otherwise, and by default, the response includes status and message keys.

   :returns:

             JSON response with validation results or error message.
                 - 200: Successful validation with result.
                 - 400: Missing email key in request.
                 - 402: Insufficient credits.
                 - 500: Internal server error.
                 - 503: Validation service unavailable.
   :rtype: Response