feat(replays): add public API endpoint documentation for replays index and details #53526

michellewzhang · 2023-07-25T17:35:14Z

Added documentation for the replays index & replays details public endpoint API.
Relates to getsentry/team-replay#112

Index:

Details:

src/sentry/replays/post_process.py

JoshFerge · 2023-07-25T17:50:57Z

src/sentry/replays/post_process.py


    """Return only the fields requested by the client."""
    if fields:
        for item in response:
-            yield {field: item[field] for field in fields}
+            yield {field: item[field] for field in fields}  # type: ignore


there may be a way to fix so we don't have to type ignore, but reading here python/mypy#7178 seems like guaranteeing dictionary key access of TypeDicts are annoying. @getsentry/python-typing anyone here have ideas?

the fields should be a list[Literal['possible', 'keys', 'here']] | None I believe

though it feels weird to only return some of the fields like this -- are there explicit subsets that we can type directly rather than allowing any combination of fields to be sliced out?

unfortunately, no. The fields returned are specified by the user via query string to the endpoint.

but we can try the literal and see if that works.

can we just give them everything and remove / deprecate that behaviour? what's the risk in giving everything?

unfortunately some fields result in expensive clickhouse queries, and it's better to leave them off by default.

maybe I'm misreading this -- but haven't they already been fetched at this point?

right, yeah. we set default values below if none were returned from the query. we may be able to refactor to make a bit more type friendly/clear. thanks

codecov · 2023-07-25T18:01:59Z

Codecov Report

Merging #53526 (e0bc7eb) into master (7b1bd66) will increase coverage by 0.00%.
Report is 7 commits behind head on master.
The diff coverage is 100.00%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #53526   +/-   ##
=======================================
  Coverage   79.55%   79.56%           
=======================================
  Files        4942     4943    +1     
  Lines      208999   209085   +86     
  Branches    35582    35590    +8     
=======================================
+ Hits       166270   166356   +86     
- Misses      37652    37654    +2     
+ Partials     5077     5075    -2

Files Changed	Coverage Δ
src/sentry/apidocs/build.py	`25.00% <ø> (ø)`
src/sentry/apidocs/examples/replay_examples.py	`100.00% <100.00%> (ø)`
...y/replays/endpoints/organization_replay_details.py	`94.59% <100.00%> (+1.73%)`	⬆️
...try/replays/endpoints/organization_replay_index.py	`100.00% <100.00%> (ø)`
src/sentry/replays/post_process.py	`95.27% <100.00%> (+4.65%)`	⬆️

... and 7 files with indirect coverage changes

src/sentry/replays/endpoints/organization_replay_details.py

schew2381 · 2023-07-26T00:39:01Z

src/sentry/replays/endpoints/organization_replay_details.py

    def get(self, request: Request, organization: Organization, replay_id: str) -> Response:
+        """
+        Retrieve a single replay instance.


More in line with what we have on our docs.

Suggested change

Retrieve a single replay instance.

Return details on an individual replay.

schew2381 · 2023-07-26T00:43:30Z

src/sentry/replays/endpoints/organization_replay_index.py

@@ -32,7 +42,21 @@ def get_replay_filter_params(self, request, organization):

        return filter_params

+    @extend_schema(
+        operation_id="Query for a List of Replays",


Endpoints that return a list are usually titled List ... (eg: List an Organization's Teams). Ideally we would do the same here, but I'm unfamiliar with how replays work. Is the returned list of replays tied to some project or something else that we can include in the title?

I'll change it to something like "List an Organization's Replays" since replays are associated by org slug

schew2381 · 2023-07-26T00:44:30Z

src/sentry/replays/endpoints/organization_replay_index.py

    def get(self, request: Request, organization: Organization) -> Response:
+        """
+        Query for a list of replays using the Replays GET Request.


Similar to above, ideally this would be like the description in List a Team's Projects

Suggested change

Query for a list of replays using the Replays GET Request.

Return a list of replays ...

feat(replays): add public API endpoint documentation for replays index

ca67666

michellewzhang requested review from JoshFerge and cmanallen July 25, 2023 17:35

michellewzhang requested review from a team as code owners July 25, 2023 17:35

github-actions bot added the Scope: Backend Automatically applied to PRs that change backend components label Jul 25, 2023

JoshFerge reviewed Jul 25, 2023

View reviewed changes

src/sentry/replays/post_process.py Show resolved Hide resolved

JoshFerge reviewed Jul 25, 2023

View reviewed changes

src/sentry/replays/post_process.py Outdated Show resolved Hide resolved

JoshFerge reviewed Jul 25, 2023

View reviewed changes

JoshFerge requested review from a team July 25, 2023 17:51

michellewzhang added 3 commits July 25, 2023 11:48

Merge branch 'master' into mz/add-replay-idx-apidoc

34c143f

add replay details documentation

fabbc3a

add replay details documentation

d3515e3

vercel bot deployed to Preview July 25, 2023 18:55 View deployment

This comment was marked as resolved.

Sign in to view

fix failing tests

eb8477d

vercel bot deployed to Preview July 25, 2023 20:25 View deployment

michellewzhang requested a review from JoshFerge July 25, 2023 20:30

michellewzhang changed the title ~~feat(replays): add public API endpoint documentation for replays index~~ feat(replays): add public API endpoint documentation for replays index and details Jul 25, 2023

Merge branch 'master' into mz/add-replay-idx-apidoc

f38e26a

vercel bot deployed to Preview July 25, 2023 22:18 View deployment

michellewzhang added 5 commits July 25, 2023 15:23

feat(replays): add public API endpoint documentation for replays index

d5d505e

add replay details documentation

dc76c7a

add replay details documentation

c41e9cc

fix merge conflicts??

3b37945

Merge branch 'master' into mz/add-replay-idx-apidoc

8a27efb

vercel bot deployed to Preview July 25, 2023 23:13 View deployment

michellewzhang force-pushed the mz/add-replay-idx-apidoc branch from 8a27efb to 3b37945 Compare July 25, 2023 23:38

vercel bot deployed to Preview July 25, 2023 23:41 View deployment

michellewzhang added 2 commits July 25, 2023 16:49

Merge branch 'mz/add-replay-idx-apidoc' into mz/replay-apidoc-merge

a37c56a

fix merge conflicts

5828d3a

vercel bot deployed to Preview July 25, 2023 23:56 View deployment

final changes

c4f7ced

vercel bot deployed to Preview July 26, 2023 00:21 View deployment

schew2381 reviewed Jul 26, 2023

View reviewed changes

src/sentry/replays/endpoints/organization_replay_details.py Outdated Show resolved Hide resolved

michellewzhang force-pushed the mz/add-replay-idx-apidoc branch from 59ab545 to e99defc Compare July 26, 2023 00:34

schew2381 self-requested a review July 26, 2023 00:34

fix capitalization

4237e43

michellewzhang force-pushed the mz/add-replay-idx-apidoc branch from e99defc to 4237e43 Compare July 26, 2023 00:35

vercel bot deployed to Preview July 26, 2023 00:39 View deployment

schew2381 reviewed Jul 26, 2023

View reviewed changes

update description and title wording

e0bc7eb

michellewzhang requested review from schew2381 and asottile-sentry July 26, 2023 02:41

vercel bot deployed to Preview July 26, 2023 02:42 View deployment

JoshFerge approved these changes Jul 26, 2023

View reviewed changes

michellewzhang merged commit 10f9c5e into master Jul 26, 2023
56 of 57 checks passed

michellewzhang deleted the mz/add-replay-idx-apidoc branch July 26, 2023 20:48

michellewzhang restored the mz/add-replay-idx-apidoc branch July 26, 2023 23:38

michellewzhang deleted the mz/add-replay-idx-apidoc branch July 26, 2023 23:38

JoshFerge mentioned this pull request Jul 27, 2023

bug(api-docs): Validate path parameters have description in api docs build #53753

Closed

github-actions bot locked and limited conversation to collaborators Aug 11, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(replays): add public API endpoint documentation for replays index and details #53526

feat(replays): add public API endpoint documentation for replays index and details #53526

michellewzhang commented Jul 25, 2023 •

edited

JoshFerge Jul 25, 2023

asottile-sentry Jul 25, 2023

JoshFerge Jul 25, 2023

JoshFerge Jul 25, 2023

asottile-sentry Jul 25, 2023

JoshFerge Jul 25, 2023

asottile-sentry Jul 25, 2023

JoshFerge Jul 25, 2023

codecov bot commented Jul 25, 2023 •

edited

This comment was marked as resolved.

This comment was marked as resolved.

schew2381 Jul 26, 2023

schew2381 Jul 26, 2023

michellewzhang Jul 26, 2023

schew2381 Jul 26, 2023

	Retrieve a single replay instance.
	Return details on an individual replay.

	Query for a list of replays using the Replays GET Request.
	Return a list of replays ...

feat(replays): add public API endpoint documentation for replays index and details #53526

feat(replays): add public API endpoint documentation for replays index and details #53526

Conversation

michellewzhang commented Jul 25, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Jul 25, 2023 • edited

Codecov Report

This comment was marked as resolved.

This comment was marked as resolved.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michellewzhang commented Jul 25, 2023 •

edited

codecov bot commented Jul 25, 2023 •

edited