"Data flow in Site Kit"

[eclarke1]

Feature Description

• Should explain relationship between Google APIs, Site Kit’s REST data points and data store (e.g. every Google API endpoint has a “proxy” REST data point)
• Should touch on the caching of API responses client-side

---

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

Acceptance criteria

• The "Data flow in Site Kit" article should be written.
• It should holistically outlined the data flow (from client to WP REST API to Google API) architecture, but specifically (as part of that) cover the bullet points in the issue description above.
• It should follow the contributor documentation best practices. Please re-read them before starting to write.
  • The article should have roughly between 500-2000 words - no hard limits though. Since this is more of an introduction to a topic, it can likely stay below 1000.
  • Also before writing, please review the list of all (eventual) articles in the TOC - if you refer to anything that is closely related to an article heading there, or if you refer to something that "undoubtedly" will be covered in a specific other article there, please includes links to such articles, even if they aren't written yet.
  • All links to other articles should be relative (i.e. work in the current branch you're in).
• The "(TODO)" annotation in the article itself and in the TOC should be removed.

Implementation Brief

Instead of a regular IB, please provide your proposed document outline (nested list of headings) for the article here. Use headings that the article could actually use, not just some brainstorm type of preliminary heading. Please assign to @felixarntz for IB review, specifically since this is one of the first articles in the epic.

• Introduction Explain in general why it is important to understand how data flows in Site Kit and which approach we use to send requests from the browser to Google Services API. No need to go into details just yet. Maybe add a sequence diagram (you can use plantuml to create one) to visualize the data flow.
• Prepare and send requests on the frontend Explain how we send requests to our API from datastore actions on the frontend. Reference the Data store architecture article and briefly mention the createFetchStore, so users know where to look at when they need to create their own fetch store.
• Process requests on the backend Explain how we define new REST API endpoints for modules (get_datapoint_definitions, create_data_request, parse_data_response) and for the core (using custom REST_Route instances). Tell how to define required scopes for module endpoints and how to prevent insecure access to endpoints.
• Connecting Google Services API* In this section we need to explain how to set up services for a module using the setup_services method and how to use it to call Google API in the module endpoints.
• Summary Briefly summarize what needs to be done to be able to send and receive data using API requests.

Test Coverage

• N/A

QA Brief

• No QA for this issue as it's only docs.

Changelog entry

[eclarke1]

@felixarntz @aaemnnosttv @marrrmarrr this was one of the 4 articles voted highest priority by engineers so if possible to progress this through the workflow along with the others labelled 'Type: Docs' and have P1 assigned.

[felixarntz]

@eugene-manuilov IB mostly looks good, however I have one concern:

and explain in detail how createFetchStore works and how users can create their own fetch stores

This should be part of the referenced "Data store architecture" docs instead. The article here should focus more on high-level concepts and doesn't need to go into actual code as much - it's the first article in the Architecture section, so it's more important to explain the flow, the relationships of different pieces, maybe naming conventions, etc. We don't need to cover how exactly to write the client-side and server-side parts of an endpoint here - it's okay to use code pointers, but the article itself shouldn't focus on code.

Other than this one point, I think the outline looks solid.

[eugene-manuilov]

@felixarntz, IB is updated. Does it look better?

[felixarntz]

@eugene-manuilov Looks good, IB ✅

[aaemnnosttv]

@tofumatt left a few comments here but overall I think it's good to go. I'm also happy for someone else to give it a final look over to not be a blocker here if you'd like, but this can probably also be a quick final review from me before merging.