Add `shopify-app-remix` scopes API documentation #1506

RyanDJLee · 2024-09-13T19:59:26Z

Closes: https://github.com/Shopify/develop-app-runtime-primitives/issues/496

#gsd:39564

WHY are these changes introduced?

Spin url: https://shopify-dev.shopify-dev-3h44.allen-chazhoor.us.spin.dev/docs/api/shopify-app-remix/v3/apis/scopes
(resume on Spin Control if necessary)

WHAT is this pull request doing?

Type of change

Documentation

Patch: Bug (non-breaking change which fixes an issue)
Minor: New feature (non-breaking change which adds functionality)
Major: Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

I have used pnpm changeset to create a draft changelog entry (do NOT update the CHANGELOG.md files manually)
I have added/updated tests for this change
I have documented new APIs/updated the documentation for modified APIs (for public APIs)

Co-authored-by: Jonathan J Chang <jonathan.j.chang@shopify.com>

Co-authored-by: Allen Chazhoor <allen.chazhoor@shopify.com>

…uery Co-authored-by: Allen Chazhoor <allen.chazhoor@shopify.com>

pobed2 · 2024-09-16T19:34:35Z

packages/apps/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.doc.ts

@@ -32,6 +32,7 @@ const data: ReferenceEntityTemplateSchema = {
    'EmbeddedAdminContext',
    'AdminApiContext',
    'BillingContext',
+    'ScopesApiContext',


The page with these examples is so weird. There are no headers between the sets of examples, so it looks like everything is related, even though there are billing things mixed in with scopes. Maybe not something for us to fix, but it feels like something to flag to Learn?

+1, this page is problematic.
+1, not necessarily something we need to fix here, but would be great to rethink this page & its purpose

pobed2 · 2024-09-16T19:37:27Z

.../apps/shopify-app-remix/src/server/authenticate/admin/scope/authenticate.admin.scopes.doc.ts

+const data: ReferenceEntityTemplateSchema = {
+  name: 'Scopes',
+  description:
+    'Contains functions used to manage optional scopes for your app.\n\nThis object is returned on authenticated Admin requests.',


Suggested change

'Contains functions used to manage optional scopes for your app.\n\nThis object is returned on authenticated Admin requests.',

'Contains functions used to manage scopes for your app.\n\nThis object is returned on authenticated Admin requests.',

I remember Jake making a point to say that this was the "scopes api", not the "optional scopes api". What do you think?

Separate question: how are scopes managed for the storefront API? We don't want optional scopes for the storefront API, right?

.../apps/shopify-app-remix/src/server/authenticate/admin/scope/authenticate.admin.scopes.doc.ts

packages/apps/shopify-app-remix/src/server/authenticate/admin/types.ts

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

…embedded app auth strat section

kbav

Love seeing this and all the work you've put into it, Ryan! Thank you for working on this 🙌

I'm in process of reviewing this and I have a dumb question... but where does the code for the examples on the right live?

For example, for the query method, I was going to propose a few changes

rather than set up a Resource Route we POST to for retrieving data through action, we could show using a Resource Route for retrieving data through loader. The useRouteLoaderData hook can be used for scenarios like this to then pull in data from other routes
request method example was a bit convoluted (may be clearer to just have an action and button on the same page, instead of using a Resource Route) and not clear that it leads to a full page redirect.

I was about to write "similar to the above" for the revoke method but now I'm wondering if it would just be overall better to demonstrate these being used in loaders and actions right on the same page. It’s a bit less mental overhead for looking at the examples, and would change the examples from having 3 tabs/files to 2 tabs/files — importantly, with all the relevant details in the first/visible tab.

What do you think about that suggestion?

kbav · 2024-09-27T00:14:23Z

packages/apps/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.doc.ts

@@ -32,6 +32,7 @@ const data: ReferenceEntityTemplateSchema = {
    'EmbeddedAdminContext',
    'AdminApiContext',
    'BillingContext',
+    'ScopesApiContext',


+1, this page is problematic.
+1, not necessarily something we need to fix here, but would be great to rethink this page & its purpose

packages/apps/shopify-app-remix/docs/staticPages/index.doc.ts

.../apps/shopify-app-remix/src/server/authenticate/admin/scope/authenticate.admin.scopes.doc.ts

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

allenchazhoor · 2024-09-27T20:27:24Z

Put up the recent changes here: https://shopify-dev.shopify-dev-3h44.allen-chazhoor.us.spin.dev/docs/api/shopify-app-remix/v3/apis/scopes

RyanDJLee · 2024-09-30T14:51:15Z

I'm in process of reviewing this and I have a dumb question... but where does the code for the examples on the right live?

No worries, it's different from ABN docs in that the code examples are directly in the docstring here. I think the current docs on the Spin instance are also outdated as we decided to remove the button examples per Pierre's feedback and to be more consistent with the rest of the documentation that simply show an action or loader.

rather than set up a Resource Route we POST to for retrieving data through action, we could show using a Resource Route for retrieving data through loader. The useRouteLoaderData hook can be used for scenarios like this to then pull in data from other routes
request method example was a bit convoluted (may be clearer to just have an action and button on the same page, instead of using a Resource Route) and not clear that it leads to a full page redirect.

I'm on board with using a Resource Route like Billing here. We chose to use an action as it is consistent with our getting started app, but we should use the correct primitives that Remix provides.

I was about to write "similar to the above" for the revoke method but now I'm wondering if it would just be overall better to demonstrate these being used in loaders and actions right on the same page. It’s a bit less mental overhead for looking at the examples, and would change the examples from having 3 tabs/files to 2 tabs/files — importantly, with all the relevant details in the first/visible tab.

I address this in the first part of my response above - we did choose to remove the button completely and reduce to 2 tabs with a focus on just the action. Apologies for not updating the instance.

What do you think about that suggestion?
cc @allenchazhoor

allenchazhoor · 2024-10-02T14:01:13Z

I've replaced the usage of actions to use loaders. Because we removed the button files, I believe the examples in their current state are accurate but please let me know if more additions/adjustments need to be made.

cc @RyanDJLee @kbav

allenchazhoor · 2024-10-02T14:02:26Z

There is also this comment from the App Bridge PR that I believe is relevant here

kbav

Sorry if I steered you wrong re: converting all to use loader; if I did, I meant to just request that for the query example. I think the other two could leverage a resource route pattern, much like Ryan & co. leveraged for making the optional scopes test app

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

kbav · 2024-10-03T18:42:23Z

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

+   *
+   *import { authenticate } from "../shopify.server";
+   *import { AuthScopes } from "@shopify/shopify-api";
+   *export async function loader({


From the context below, it looks like this is being set up more specifically as an action: request.formData(), etc.

I think the query makes sense in a loader, but request perhaps best makes sense as part of a resource route's action, and perhaps the same for revoke. Worth testing for those

kbav · 2024-10-03T18:44:31Z

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

+  /**
+   * Revokes the provided scopes from this app on this shop
+   *
+   * **Warning:** This method throws an [error](https://shopify.dev/docs/api/admin-graphql/unstable/objects/AppRevokeAccessScopesAppRevokeScopeError) if the provided optional scopes contains a required scope. 


If other API’s don't use this pattern of adding a bolded "Warning", I'd consider dropping the word entirely

packages/apps/shopify-app-remix/src/server/authenticate/admin/scope/types.ts

Ryan DJ Lee and others added 3 commits September 12, 2024 15:27

Add documentation for Scopes API

229b82d

Co-authored-by: Jonathan J Chang <jonathan.j.chang@shopify.com>

Remove unnecessary code in examples

bc30277

Co-authored-by: Allen Chazhoor <allen.chazhoor@shopify.com>

Add description for ScopesRevokeResponse and update return type for Q…

9ba91ec

…uery Co-authored-by: Allen Chazhoor <allen.chazhoor@shopify.com>

RyanDJLee self-assigned this Sep 13, 2024

github-actions bot added the cla-needed label Sep 13, 2024

RyanDJLee assigned allenchazhoor Sep 13, 2024

RyanDJLee requested review from kbav, pobed2 and zzooeeyy September 13, 2024 19:59

pobed2 reviewed Sep 16, 2024

View reviewed changes

allenchazhoor added 3 commits September 19, 2024 17:00

Add references to Managing Access Scopes and Scopes API pages in new …

e07ef8f

…embedded app auth strat section

Move link reference to Managing your Scopes page

5e80afa

Add changeset

af3f849

allenchazhoor force-pushed the scopes-api-documentation branch from 28d879f to af3f849 Compare September 24, 2024 18:05

allenchazhoor added 6 commits September 24, 2024 14:06

Merge branch 'main' into scopes-api-documentation

4a4fa18

Add more details to Request API description

be81816

remove unneeded explicit use of "optional" in descriptions

8b12914

Replace changeset with minor change tag rather than major

0a280b6

remove future flags from example code

d9762f2

Remove redundant suggestion to perform on validation on request calls

abb7a3d

kbav reviewed Sep 27, 2024

View reviewed changes

allenchazhoor added 4 commits September 27, 2024 14:52

Remove frontend button and handler code from examples

62b3a09

correct capitalization for managing access scopes

281551b

change usage of "functions" to "methods"

7baa3db

fix typo with redundant word

6a360b3

replace example usage of actions with loaders

e1d06f0

allenchazhoor added 2 commits October 2, 2024 10:27

Add colon after warnings

fced03e

Remove advice to perform on validation on Revoke and link error docs

d6dc083

kbav reviewed Oct 3, 2024

View reviewed changes

allenchazhoor added 6 commits October 5, 2024 12:09

reword to reinforce scopesDetail return

43484d5

revert the request and revoke examples to use actions

30dd6ac

remove server.ts example files

8447777

unbold warnings

74ac25e

fix whitespace and linting issues

8115b96

Merge branch 'main' into scopes-api-documentation

f6922ad

allenchazhoor changed the title ~~[WIP] add shopify-app-remix scopes API documentation~~ Add shopify-app-remix scopes API documentation Oct 7, 2024

allenchazhoor marked this pull request as ready for review October 7, 2024 14:09

allenchazhoor requested a review from a team as a code owner October 7, 2024 14:09

allenchazhoor added 10 commits October 8, 2024 19:04

Add Index functions for query and revoke

e8d46d4

change revoke file to ts from tsx

fb032d8

fix linting issues

f7eff96

Merge branch 'main' into scopes-api-documentation

54c7bf0

fix spacing in code example

15eb37e

fix revoke imports

9a22943

update spacing

fc1de5b

update query method to check scope inclusion

482a8b9

Merge branch 'main' into scopes-api-documentation

cb9f93c

run eslint

3885493

lizkenyon mentioned this pull request Oct 30, 2024

Remove future flag for released feature #1705

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `shopify-app-remix` scopes API documentation #1506

Add `shopify-app-remix` scopes API documentation #1506

RyanDJLee commented Sep 13, 2024 •

edited by allenchazhoor

Loading

pobed2 Sep 16, 2024

kbav Sep 27, 2024

pobed2 Sep 16, 2024

pobed2 Sep 16, 2024

kbav left a comment

kbav Sep 27, 2024

allenchazhoor commented Sep 27, 2024 •

edited

Loading

RyanDJLee commented Sep 30, 2024

allenchazhoor commented Oct 2, 2024

allenchazhoor commented Oct 2, 2024

kbav left a comment

kbav Oct 3, 2024

kbav Oct 3, 2024

	'Contains functions used to manage optional scopes for your app.\n\nThis object is returned on authenticated Admin requests.',
	'Contains functions used to manage scopes for your app.\n\nThis object is returned on authenticated Admin requests.',

Add shopify-app-remix scopes API documentation #1506

Are you sure you want to change the base?

Add shopify-app-remix scopes API documentation #1506

Conversation

RyanDJLee commented Sep 13, 2024 • edited by allenchazhoor Loading

WHY are these changes introduced?

WHAT is this pull request doing?

Type of change

Checklist

pobed2 Sep 16, 2024

Choose a reason for hiding this comment

kbav Sep 27, 2024

Choose a reason for hiding this comment

pobed2 Sep 16, 2024

Choose a reason for hiding this comment

pobed2 Sep 16, 2024

Choose a reason for hiding this comment

kbav left a comment

Choose a reason for hiding this comment

kbav Sep 27, 2024

Choose a reason for hiding this comment

allenchazhoor commented Sep 27, 2024 • edited Loading

RyanDJLee commented Sep 30, 2024

allenchazhoor commented Oct 2, 2024

allenchazhoor commented Oct 2, 2024

kbav left a comment

Choose a reason for hiding this comment

kbav Oct 3, 2024

Choose a reason for hiding this comment

kbav Oct 3, 2024

Choose a reason for hiding this comment

Add `shopify-app-remix` scopes API documentation #1506

Add `shopify-app-remix` scopes API documentation #1506

RyanDJLee commented Sep 13, 2024 •

edited by allenchazhoor

Loading

allenchazhoor commented Sep 27, 2024 •

edited

Loading