Implement User Surveys REST Controller

Feature Description

In #3355, we defined a number of actions that rely on REST endpoints that do not yet exist. This issue is for adding the necessary handling for those on the server side.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• A Google\Site_Kit\Core\User_Surveys\REST_User_Surveys_Controller class should be implemented, similar to the REST_Feature_Tours_Controller
  • Dependencies should be provided as needed via the constructor
  • Should have a test case added for it (see REST_Feature_Tours_ControllerTest)
• It should register the following REST routes and corresponding remote endpoints on the Site Kit service:
  • POST:core/user/data/survey-trigger
    • Requires a triggerID as a non-empty string request parameter
    • Forwards request to the Site Kit service as POST:/survey/trigger/ with JSON-encoded body:
      • site_id: Current site ID.
      • site_secret: Current site secret.
      • access_token: Current user’s access token.
      • trigger_context: An object containing the following fields:
        • trigger_id: The trigger ID, as received from the client.
        • language: Current user’s WP locale
    • Response should be returned back to the client
  • POST:core/user/data/survey-event
    • Requires an event object passed from the client
    • Requires a session object passed from the client with session_id and session_token fields
    • Forwards request to the Site Kit service as POST:/survey/event/ with JSON-encoded body:
      • site_id: Current site ID.
      • site_secret: Current site secret.
      • access_token: Current user’s access token.
      • session: Object with session_id and session_token fields received from the client
      • event: Object with data passed from the client
    • Response should be returned back to the client
• All routes must require the user to be authenticated
• All routes require that the site is connected via the proxy

Implementation Brief

Google_Proxy class

• Add a new public method send_survey_trigger( $credentials, $access_token, $trigger_id ).
  • It should call the Google_Proxy::request method passing /survey/trigger/ as the first argument, the incoming $credentials object as the second argument, and an array with the following fields as the third argument:

    'access_token' => $access_token`,
    'json_request' => true,
    'body' => array(
        'trigger_context' => array(
            'trigger_id' => $trigger_id,
            'language' => ... // current user locale
        ),
    ),
    

  • Return results of the request method call without modifications.
• Add a new public method send_survey_event( $credentials, $access_token, $session, $event ).
  • It should follow the logic from the send_survey_trigger method but use /survey/event/ as the first parameter and the following array as the body property of the array passed as the third parameter:

    'session' => $session,
    'event' => $event,
    

REST_User_Surveys_Controller class

• Create a new class REST_User_Surveys_Controller in the includes/Core/User_Surveys folder. Use REST_Feature_Tours_Controller as an example in terms of registering routes, the methods to implement, etc.
  • Add a public constructor that accepts only the Authentication $authentication argument.
  • Add a new protected method get_rest_routes that returns an array of REST_Route objects for the endpoints defined in the AC. Each REST route should do the following:
    • Verify that the current user is authenticated (using $authentication->is_authenticated()) and proxy is used (using $authentication->credentials()->using_proxy()) in the permission_callback property.
    • Define the args property with the expected schema for the incoming arguments. See how we did it for the user input settings: https://github.com/google/site-kit-wp/blob/43dd2936086ea4b9bda71d038abb4b343fe981e5/includes/Core/REST_API/REST_Routes.php#L318-L348
    • Call the appropriate method of the Google_Proxy class (defined above) to send a request to the proxy server and return a response from it.
      • Use Google_Proxy class instance by calling $authentication->get_google_proxy() to get the instance of the Google_Proxy class.
      • Use $authentication->get_oauth_client()->get_access_token() to get the access token.
      • Use $authentication->credentials() to get the credentials object.
  • Add a new public method register that adds a new hook for the googlesitekit_rest_routes filter. The hook should merge the incoming $routes with the REST routes returned by the get_rest_routes method. See how it’s done in the feature tours controllers: https://github.com/google/site-kit-wp/blob/43dd2936086ea4b9bda71d038abb4b343fe981e5/includes/Core/Feature_Tours/REST_Feature_Tours_Controller.php#L76-L81
• Register the REST_User_Surveys_Controller class in the hook for the init action defined in the Plugin::register method. You can do it like this: https://github.com/google/site-kit-wp/blob/43dd2936086ea4b9bda71d038abb4b343fe981e5/includes/Plugin.php#L191

Test Coverage

• Create new phpunit tests for the REST_User_Surveys_Controller class. See REST_Feature_Tours_ControllerTest for inspiration on how to structure this file.
  • Ensure the ACs are met in these unit tests.

Visual Regression Changes

• N/A

QA Brief

• Check the Google_Proxy class and verify that it has two new public methods: send_survey_trigger and send_survey_event. Those methods should satisfy requirements defined for forwarded requests to the proxy server defined in the AC.
• Check the REST_User_Surveys_Controller class and verify that it registers two endpoints: POST:core/user/data/survey-trigger and POST:core/user/data/survey-event. Also, validate that those endpoints satisfy requirements defined in the AC and call the appropriate methods from the Google_Proxy class.

Changelog entry

• Add REST routes for user survey endpoints.

[felixarntz]

@aaemnnosttv @eugene-manuilov I’ve updated the ACs here to also require passing the site_secret to the proxy - originally it only required passing site_id. Looking at the PR #3440, this is already the case anyway (since the regular Google_Proxy method for sending a request does just that), so this doesn’t require any additional work on the plugin side. I was gonna open a new issue, but it looks like that’s not needed.

[aaemnnosttv]

@aaemnnosttv AC says to proxy survey-trigger and survey-event to the same /survey/trigger/ endpoint. Is it intentional? Shouldn’t core/user/data/survey-event request be proxied to the /survey/event/ endpoint?

@eugene-manuilov – yes, correct. I’ve updated it in the ACs, thanks for checking!

One point is that the most obvious way to me to make HTTP requests to the Proxy in this case is using the private request() method, but… it’s private. It’s not clear to me why such a method would be private given it’s quite a useful thing to expose for other parts of the plugin that want to make requests to the proxy. So I say we make it public, but I’ll admit the layers of classes and the approach to the REST Client section of the plugin isn’t intuitive to me and I might have that approach totally wrong.

@tofumatt I agree although I’m not sure if this was previously discussed (@eugene-manuilov?). My guess is that it was made private by default since we didn’t have a use for it outside of that class yet.

@eugene-manuilov if the IB needs further iteration how do you feel about taking over and then assigning to me for review? The IB is looking pretty close at first glance, but as @tofumatt said the issue is a bit timely and it’s important we move this forward today.