From 77ab36ca816516a677b736a46eec59aeed36a055 Mon Sep 17 00:00:00 2001 From: Nelson Date: Thu, 20 Jul 2023 11:58:45 -0400 Subject: [PATCH] more doc improvements (#1185) * Rails context links, cleaned up removed methods * remove session issues docs as session storage has been removed --- README.md | 5 ++++- docs/README.md | 1 - docs/issues.md | 39 --------------------------------------- docs/usage/graphql.md | 3 --- docs/usage/oauth.md | 5 +++++ docs/usage/rest.md | 15 +++++---------- docs/usage/webhooks.md | 15 +++++++++------ 7 files changed, 23 insertions(+), 60 deletions(-) delete mode 100644 docs/issues.md diff --git a/README.md b/README.md index c8d2cc12b..5c2e3d6c6 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ You can use this library in any application that has a Ruby backend, since it do **Note**: These instructions apply to v10 or later of this package. If you're running v9 in your app, you can find the documentation [in this branch](https://github.com/Shopify/shopify-api-ruby/tree/v9). +## Use with Rails +If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to interact with this gem. Authentication, session storage, webhook regirstration, and other frequenly implemented paths are managed in that gem with easy to use configurations. + ## Requirements To follow these usage guides, you will need to: @@ -93,7 +96,7 @@ Please refer to [the documentation](docs/getting_started.md) in this repository With this, a lot changed in how apps access the library. Here are the updates you should make when migrating to v10: - Call `ShopifyAPI::Context.setup` when setting up your app. This class holds global configurations for your app and defines how the library behaves. -- If not using the `shopify_app` gem, your app needs to provide an implementation of `ShopifyAPI::Auth::SessionStorage` for production. Read more about this [in our documentation](docs/usage/session_storage.md). +- If not using the [shopify_app](https://github.com/Shopify/shopify_app) gem, your app needs to provide an implementation of `ShopifyAPI::Auth::SessionStorage` for production. Read more about this [in our documentation](docs/usage/session_storage.md). - To change the `User-Agent` header, use `user_agent_prefix` in `ShopifyAPI::Context.setup`. - Usages of the `ActiveResource` classes for REST API requests need to be refactored into the new format. You can find detailed examples on how each of the endpoints work in our [reference documentation](https://shopify.dev/docs/api/admin-rest). diff --git a/docs/README.md b/docs/README.md index 921053627..410c07ed3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,4 +10,3 @@ You can follow our getting started guide to learn how to use this library. - [Make a GraphQL API call](usage/graphql.md) - [Make a Storefront API call](usage/graphql_storefront.md) - [Webhooks](usage/webhooks.md) -- [Known issues and caveats](issues.md) diff --git a/docs/issues.md b/docs/issues.md deleted file mode 100644 index 88fc188f2..000000000 --- a/docs/issues.md +++ /dev/null @@ -1,39 +0,0 @@ -# Known issues and caveats - -By following this guide, you will have a fully functional Shopify app. However, there are some things you should be aware of before using your new app in a production environment. - -## Notes on session handling - -Before you start writing your application, please note that the Shopify library needs to store some information for OAuth in sessions. Since each application may choose a different strategy to store information, the library cannot dictate any specific storage strategy. When calling `ShopifyAPI::Context.setup`, you'll need to provide an instance of a class that implements the `ShopifyAPI::Auth::SessionStorage` interface. - -This library provides a very simple implementation of that interface which stores sessions in files, `ShopifyAPI::Auth::FileSessionStorage` ([source code](../lib/shopify_api/auth/file_session_storage.rb)). This class is meant to speed up development with this library, but it is not suitable for production use, because it will lead to disk build-up as old sessions are not cleaned up. - -Before you deploy your app to production, it should use your selected storage method for sessions. You can do that by creating a class that implements the `SessionStorage` interface and pass that in your `Context.setup` call. Your class will need to implement the methods below. - -**Note**: After you create your implementation of `SessionStorage`, you should make sure to clean up old sessions periodically in your data storage. The library will delete some sessions when they are no longer useful, but it cannot guarantee that expired sessions are deleted automatically. - -#### `SessionStorage.storeSession` - -Creates **or updates** a `Session` object in your storage. This function should return a `bool` indicating whether the operation was successful. - -| Param | Type | Notes | -| --------- | --------- | --------------------------- | -| `session` | `Session` | The session object to store | - -#### `SessionStorage.loadSession` - -Fetches a `Session` object from your storage. This function should return a `Session` object, or `null` if it was not found. - -| Param | Type | Notes | -| ----------- | -------- | ----------------------------- | -| `sessionId` | `string` | The id of the session to load | - -#### `SessionStorage.deleteSession` - -Deletes a session from your storage. This function should return a `bool` indicating whether the operation was successful. - -| Param | Type | Notes | -| ----------- | -------- | ------------------------------- | -| `sessionId` | `string` | The id of the session to delete | - -[Back to guide index](README.md) \ No newline at end of file diff --git a/docs/usage/graphql.md b/docs/usage/graphql.md index 6e00bfce6..a86f40f02 100644 --- a/docs/usage/graphql.md +++ b/docs/usage/graphql.md @@ -5,9 +5,6 @@ Once you have a [session](oauth.md#fetching-sessions) after completing oauth, yo Below is an example ```ruby -# load the current session with SessionUtils.load_current_session -session = ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: , cookies: , is_online: ) - # initalize the client client = ShopifyAPI::Clients::Graphql::Admin.new(session: session) diff --git a/docs/usage/oauth.md b/docs/usage/oauth.md index 1147dae05..7d4210ef5 100644 --- a/docs/usage/oauth.md +++ b/docs/usage/oauth.md @@ -5,6 +5,11 @@ Once the library is set up for your project, you'll be able to use it to start a To do this, you can follow the steps below. For more information on authenticating a Shopify app please see the [Types of Authentication](https://shopify.dev/docs/apps/auth#types-of-authentication) page. +## Note about Rails +If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to perform OAuth. + +If you aren't using Rails, you can look at how that [gem creates / stores sessions from the OAuth flow](https://github.com/Shopify/shopify_app/blob/2f90af43173041d145f578dcd6448f238b69f9fe/app/controllers/shopify_app/callback_controller.rb#L9) for further examples. + ## Add a route to start OAuth The route for starting the OAuth process (in this case `/login`) will use the library's `begin_auth` method. The method will return an `auth_route` URI that will be used for redirecting the user to the Shopify Authentication screen and a session cookie to store on the user's browser. These return values will be a hash in the form of {`auth_route`: `String`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`} diff --git a/docs/usage/rest.md b/docs/usage/rest.md index 1c4f8546b..8c7438775 100644 --- a/docs/usage/rest.md +++ b/docs/usage/rest.md @@ -17,13 +17,15 @@ The Rest Admin client offers the 4 core request methods: `get`, `delete`, `post` **Note:** _These paramaters can still be used in all methods regardless of if they are required._ ## Usage Examples: +### Required Session +Every request requires a valid +[ShopifyAPI::Auth::Session](https://github.com/Shopify/shopify-api-ruby/blob/f341d998cce7429b841c2c3b4ce55a18a52823e4/lib/shopify_api/auth/session.rb). + +To instantiate a session, we recommend you either use the `shopify_app` if working in Rails or refer to our [OAuth docs on constructing a session](oauth.md#fetching-sessions) ### Perform a `GET` request: ```ruby -# Load the current session to get the `accessToken`. -session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online) - # Create a new client. client = ShopifyAPI::Clients::Rest::Admin.new(session: session) @@ -37,9 +39,6 @@ some_function(response.body) ### Perform a `POST` request: ```ruby -# Load the current session to get the `accessToken`. -session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online) - # Create a new client. client = ShopifyAPI::Clients::Rest::Admin.new(session: session) @@ -78,7 +77,6 @@ After making a request, the `next_page_info` and `prev_page_info` can be found o An example of this is shown below: ```ruby -session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online) client = ShopifyAPI::Clients::Rest::Admin.new(session: session) response = client.get(path: "products", query: { limit: 10 }) @@ -95,8 +93,6 @@ Similarly, when using REST resources the `next_page_info` and `prev_page_info` c An example of this is shown below: ```ruby -session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online) - products = ShopifyAPI::Product.all(session: session, limit: 10) loop do @@ -111,7 +107,6 @@ The next/previous page_info strings can also be retrieved from the response obje An example of this is shown below: ```ruby -session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online) client = ShopifyAPI::Clients::Rest::Admin.new(session: session) response = client.get(path: "products", query: { limit: 10 }) diff --git a/docs/usage/webhooks.md b/docs/usage/webhooks.md index 824ec5628..ce1eb5e79 100644 --- a/docs/usage/webhooks.md +++ b/docs/usage/webhooks.md @@ -2,12 +2,15 @@ The `shopify_api` gem provides webhook functionality to make it easy to both subscribe to and process webhooks. To implement in your app follow the steps outlined below. +## Use with Rails +If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to interact with this gem. That gem handles [webhooks with a declarative configuration](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/webhooks.md). + ## Create a Webhook Handler If you want to register for an http webhook you need to implement a webhook handler which the `shopify_api` gem can use to determine how to process your webhook. You can make multiple implementations (one per topic) or you can make one implementation capable of handling all the topics you want to subscribe to. To do this simply make a module or class that includes or extends `ShopifyAPI::Webhooks::WebhookHandler` and implement the handle method which accepts the following named parameters: topic: `String`, shop: `String`, and body: `Hash[String, untyped]`. An example implementation is shown below: ```ruby -module WebhookHandler +module WebhookHandler include ShopifyAPI::Webhooks::Handler class << self @@ -31,11 +34,11 @@ If you are only interested in particular fields, you can optionally filter the d ```ruby registration = ShopifyAPI::Webhooks::Registry.add_registration( - topic: "orders/create", - delivery_method: :http, - handler: WebhookHandler, + topic: "orders/create", + delivery_method: :http, + handler: WebhookHandler, fields: ["number","note"] # this can also be a single comma separated string -) +) ``` **Note**: The webhooks you register with Shopify are saved in the Shopify platform, but the local `ShopifyAPI::Webhooks::Registry` needs to be reloaded whenever your server restarts. @@ -75,7 +78,7 @@ ShopifyAPI::Webhooks::Registry.register(topic: "", session: shop This will return a single `ShopifyAPI::Webhooks::RegisterResult`. -## Unregister a Webhook +## Unregister a Webhook To unregister a topic from a shop you can simply call: ```ruby