[WIP] add `shopify-app-remix` scopes API documentation #1506

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

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

WHY are these changes introduced?

Spin url: https://shopify-dev.shopify-dev-86xc.ryan-d-lee.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 <[email protected]>

Co-authored-by: Allen Chazhoor <[email protected]>

…uery Co-authored-by: Allen Chazhoor <[email protected]>

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

pobed2 · 2024-09-16T19:42:23Z

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

+   *}
+   * ```
+   * ```ts
+   * // /app/routes/**\/*.tsx


Does this file provide any value to the example? Looking at the docs on your Spin instance, It took me a minute to realize that this was a button to post at /query

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

pobed2 · 2024-09-16T19:49:26Z

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

+   *
+   *  const body = await request.formData();
+   *  const scopesToRevokeData = body.getAll("scopes") as string[];
+   *  const scopesToRevoke = new AuthScopes(scopesToRevokeData);


In the description, we call out that developers should implement their own validation to make sure the scopes are valid before passing them into scopes.revoke. Is new AuthScopes(...) doing this validation? Should we explicitly call it out in a comment like // Ensure scopes provided are valid or something?

…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

kbav · 2024-09-27T00:19:29Z

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

@@ -166,6 +166,7 @@ const data: LandingTemplateSchema = {
        "\n\nIt takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" +
        " to handle automatic app installations and scope updates, while using" +
        " [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to get an access token for the logged-in user." +
+        "\n\n If you wish to learn about Scopes Management and APIs, please read through [Managing Access Scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/managing-access-scopes)" +


Suggested change

"\n\n If you wish to learn about Scopes Management and APIs, please read through [Managing Access Scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/managing-access-scopes)" +

"\n\n If you wish to learn about scopes management and APIs, please read through [Manage access scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/managing-access-scopes)" +

kbav · 2024-09-27T00:20:00Z

.../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 scopes for your app.\n\nThis object is returned on authenticated Admin requests.',


Suggested change

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

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

kbav · 2024-09-27T00:22:07Z

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

+   *
+   * @example
+   * <caption>Request consent from the merchant to grant the provided scopes for this app.</caption>
+   * <description>Call `scopes.request` to get request optional scopes.</description>


Suggested change

* <description>Call `scopes.request` to get request optional scopes.</description>

* <description>Call `scopes.request` to request optional scopes.</description>

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 <[email protected]>

Remove unnecessary code in examples

bc30277

Co-authored-by: Allen Chazhoor <[email protected]>

Add description for ScopesRevokeResponse and update return type for Q…

9ba91ec

…uery Co-authored-by: Allen Chazhoor <[email protected]>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] add `shopify-app-remix` scopes API documentation #1506

[WIP] 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

pobed2 Sep 16, 2024

pobed2 Sep 16, 2024

kbav left a comment

kbav Sep 27, 2024

kbav Sep 27, 2024

kbav Sep 27, 2024

kbav Sep 27, 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.',

	"\n\n If you wish to learn about Scopes Management and APIs, please read through [Managing Access Scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/managing-access-scopes)" +
	"\n\n If you wish to learn about scopes management and APIs, please read through [Manage access scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/managing-access-scopes)" +

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

	* <description>Call `scopes.request` to get request optional scopes.</description>
	* <description>Call `scopes.request` to request optional scopes.</description>

[WIP] add shopify-app-remix scopes API documentation #1506

Are you sure you want to change the base?

[WIP] 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

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

kbav left a 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

[WIP] add `shopify-app-remix` scopes API documentation #1506

[WIP] add `shopify-app-remix` scopes API documentation #1506

RyanDJLee commented Sep 13, 2024 •

edited by allenchazhoor

Loading