shopify_api 13.1.0 → 13.4.0

data/docs/usage/graphql.md

@@ -1,17 +1,37 @@
 # Make a GraphQL API call
 
-Once you have a [session](oauth.md#fetching-sessions) after completing oauth, you can make GraphQL queries to the Admin API with `ShopifyAPI::Clients::Graphql::Admin`
+Once OAuth is complete, we can use `ShopifyAPI::Clients::Graphql::Admin` to make authenticated API calls to the Shopify Admin GraphQL API.
+#### Required Session
+Every API request requires a valid
+[ShopifyAPI::Auth::Session](https://github.com/Shopify/shopify-api-ruby/blob/main/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:
+ - ["Custom Apps"](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/custom_apps.md) - documentation on how to create Session from a custom app API token.
+ - ["Performing OAuth"](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/oauth.md) - documentation on how to create new sessions
+ - [[ShopifyApp] - "Session"](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md) - documentation on session handling if you're using the [`ShopifyApp`](https://github.com/Shopify/shopify_app) gem.
+
+### Instantiation
+Create an instance of [`ShopifyAPI::Clients::Graphql::Admin`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/graphql/admin.rb) using the current session to make requests to the Admin API.
+
+#### Constructor parameters
+| Parameter | Type | Notes |
+| ----------|------|-------|
+| `session` | `ShopifyAPI::Auth::Session` | Default value is `nil`. <br><br>When `nil` is passed in, active session information is inferred from `ShopifyAPI::Context.active_session`. <br>To set active session, use `ShopifyAPI::Context.activate_session`. <br><br>This is handled automatically behind the scenes if you use ShopifyApp's [session controllers](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md). |
+| `api_version` | `String` | Default value is `nil`. When `nil` is passed in, api version is inferred from [`ShopifyAPI::Context.setup`](https://github.com/Shopify/shopify-api-ruby/blob/main/README.md#setup-shopify-context).|
+
+Usage:
+```ruby
+client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")
+```
 
-Below is an example
+### Making Authenticated API calls
+#### Basic example
 
 ```ruby
-# load the current session with SessionUtils.load_current_session
-session = ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
-
-# initalize the client
+# Initialize the client
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
 
-# make the GraphQL query string
+# Make the GraphQL query string
 query =<<~QUERY
   {
     products(first: 10) {
@@ -28,10 +48,13 @@ query =<<~QUERY
 QUERY
 
 response = client.query(query: query)
+
 # do something with the response data
+product = response.body["data"]["products"]["edges"][0]
+my_function(product)
 ```
 
-You can also make GraphQL calls that take in variables
+#### Example GraphQL query with variables
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
@@ -50,18 +73,19 @@ query = <<~QUERY
     }
   }
 QUERY
+
 variables = {
   first: 3
 }
 
 response = client.query(query: query, variables: variables)
-
 ```
 
-Here is an example of how you might use fragments as part of the client
+#### Example GraphQL query with fragments
 
 ```ruby
 client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
+
 # define the fragment as part of the query
 query = <<~QUERY
   fragment ProductStuff on Product {
@@ -81,29 +105,76 @@ query = <<~QUERY
     }
   }
 QUERY
+
 variables = {
   first: 3
 }
+
 response = client.query(query: query, variables: variables)
-# do something with the reponse
+# do something with the response
 ```
 
-By default, the client uses the API version configured in `ShopifyAPI`.  To use a different API version, set the optional `api_version` parameter.  To experiment with prerelease API features, use `"unstable"` for the API version.
+
+### Output
+#### Success
+If the request is successful these methods will all return a [`ShopifyAPI::Clients::HttpResponse`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/http_response.rb) object, which has the following methods:
+| Methods | Type | Notes |
+|---------|------|-------|
+| `code`  |`Integer`| HTTP Response code, e.g. `200`|
+| `header` |`Hash{String, [String]}` | HTTP Response headers |
+| `body`  | `Hash{String, Untyped}`  | HTTP Response body |
+| `prev_page_info` | `String` | See [Pagination](#pagination)|
+| `next_page_info` | `String` | See [Pagination](#pagination)|
+
+#### Failure
+If the request has failed, an error will be raised describing what went wrong.
+You can rescue [`ShopifyAPI::Errors::HttpResponseError`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/errors/http_response_error.rb)
+and output error messages with `errors.full_messages`
+
+## Pagination
+
+This library also supports cursor-based pagination for GraphQL Admin API requests. [Learn more about GraphQL request pagination](https://shopify.dev/docs/api/usage/pagination-graphql).
+
+After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and be used in the query param in other requests.
+
+## Response as Struct
+By default the response body is returned as a `Hash{String, Untyped}`. If you would like to return the response body as a `Struct`, you can pass `response_as_struct: true` to the `ShopifyAPI::Context.setup` method.
+Then you can access the object with both dot and hash notation.
 
 ```ruby
-client = ShopifyAPI::Clients::Graphql::Admin.new(session: session, api_version: "unstable")
-```
+    ShopifyAPI::Context.setup(
+      api_key: ShopifyApp.configuration.api_key,
+      api_secret_key: ShopifyApp.configuration.secret,
+      ...
+      response_as_struct: true
+    )
 
-Want to make calls to the Storefront API? Click [here](graphql_storefront.md)
+    # Make a graphql query
+      response = client.query(
+        query: CREATE_PRODUCTS_MUTATION,
+        variables: {
+          input: {
+            title: random_title,
+            variants: [{ price: random_price }],
+          },
+        },
+      )
+      # Access result with dot notation
+      created_product2 = response.body.data.productCreate.product
+      # Access result with hash notation
+      created_product = response.body["data"]["productCreate"]["product"]
 
-# Proxy a GraphQL Query
+```
 
-If you would like to give your front end the ability to make authenticated graphql queries to the Shopify Admin API, the `shopify_api` gem makes proxying a graphql request easy! The gem provides a utility function which will accept the raw request body (a GraphQL query), the headers, and the cookies (optional). It will add authentication to the request, proxy it to the Shopify Admin API, and return a `ShopifyAPI::Clients::HttpResponse`. An example utilization of this in Rails is shown below:
+## Proxy a GraphQL Query
+
+If you would like to give your front end the ability to make authenticated graphql queries to the Shopify Admin API, the `shopify_api` gem makes proxy-ing a graphql request easy! The gem provides a utility function which will accept the raw request body (a GraphQL query), the headers, and the cookies (optional). It will add authentication to the request, proxy it to the Shopify Admin API, and return a `ShopifyAPI::Clients::HttpResponse`. An example utilization of this in Rails is shown below:
 
 ```ruby
 def proxy
   begin
     response = ShopifyAPI::Utils::GraphqlProxy.proxy_query(
+      session: session,
       headers: request.headers.to_h,
       body: request.raw_post,
       cookies: request.cookies.to_h
@@ -119,3 +190,6 @@ end
 ```
 
 **Note:** GraphQL proxying is only supported for online sessions for non-private apps, the utility will raise a `ShopifyAPI::Errors::SessionNotFoundError` if there are no existing online tokens for the provided credentials, and a `ShopifyAPI::Errors::PrivateAppError` if called from a private app.
+
+## Storefront API
+⚠️ Want to make calls to the Storefront API? [Read this](graphql_storefront.md).

data/docs/usage/oauth.md

@@ -5,17 +5,81 @@ 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.
 
-## Add a route to start OAuth
+## Session Persistence
+Session persistence is deprecated from the `ShopifyAPI` library gem since [version 12.3.0](https://github.com/Shopify/shopify-api-ruby/blob/main/CHANGELOG.md#version-1230). The responsibility of session storage typically is fulfilled by the web framework middleware.
+This API library's focus is on making requests and facilitate session creation.
 
-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`}
+⚠️ If you're not using the [ShopifyApp](https://github.com/Shopify/shopify_app) gem, you may use ShopifyAPI to perform OAuth to create sessions, but you must implement your own session storage method to persist the session information to be used in authenticated API calls.
 
+## 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, you won't have to follow the instructions below to start your own OAuth flow.
+  - See `ShopifyApp`'s [documentation on session storage](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/sessions.md#sessions)
+
+If you aren't using Rails, you can look at how the `ShopifyApp` gem handles OAuth flow for further examples:
+- [Session Controller](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/sessions_controller.rb)
+  - Triggering and redirecting user to **begin** OAuth flow
+- [Callback Controller](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/callback_controller.rb)
+  - Creating / storing sessions to **complete** the OAuth flow
+
+## Performing OAuth
+#### Steps
+1. [Add a route to start OAuth](#1-add-a-route-to-start-oauth)
+2. [Add an Oauth callback route](#2-add-an-oauth-callback-route)
+3. [Begin OAuth](#3-begin-oauth)
+4. [Handle OAuth Callback](#4-handle-oauth-callback)
+5. [Using OAuth Session to make authenticated API calls](#5-using-oauth-session-to-make-authenticated-api-calls)
+
+### 1. Add a route to start OAuth
+Add a route to your app to start the OAuth process.
+
+```ruby
+class ShopifyAuthController < ApplicationController
+  def login
+    # This method will trigger the start of the OAuth process
+  end
+end
+```
+
+### 2. Add an OAuth callback route
+After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route
+(which you will provide as the `redirect_path` parameter to `begin_auth` method, in [step 3 - Begin OAuth](#3-begin-oauth)).
+```ruby
+class ShopifyCallbackController < ApplicationController
+  def callback
+    # This callback method will be called once user grants permission to this app from Shopify Admin.
+  end
+```
+
+### 3. Begin OAuth
+Use [`ShopifyAPI::Auth::Oauth.begin_auth`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/oauth.rb#L22) method to start OAuth process for your app.
+
+#### Input
 | Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
 | -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
 | `shop`          | `String`               |    Yes    |       -       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                                            |
 | `redirect_path` | `String`               |    Yes    |       -       | The redirect path used for callback with a leading `/`. The route should be allowed under the app settings. |
 | `is_online`     | `Boolean`              |    No     |    `true`     | `true` if the session is online and `false` otherwise.                                                      |
 
-Your app should take the returned values from the `begin_auth` function and redirect the user to url defined by `auth_route` and set the cookie in the user's browser. We strongly recommend that you use secure, httpOnly cookies for this to help prevent session hijacking.
+#### Output
+`begin_auth` method will return a hash result in the form of:
+```ruby
+{
+  auth_route: String,
+  cookie: ShopifyAPI::Auth::Oauth::SessionCookie,
+}
+```
+
+| Key | Type | Notes |
+|-----|------|-------|
+|`auth_route`|`String`|URI that will be used for redirecting the user to the Shopify Authentication screen|
+|`cookie`|`ShopifyAPI::Auth::Oauth::SessionCookie`|A session cookie to store on the user's browser. |
+
+#### Example
+Your app should take the returned values from the `begin_auth` method and:
+
+1. Set the cookie in the user's browser. We strongly recommend that you use secure, httpOnly cookies for this to help prevent session hijacking.
+2. Redirect the user to authorization url defined by `auth_route`.
+   - This will redirect the user to the Shopify Admin page to authorize/grant permission to the app.
 
 An example is shown below in a Rails app but these steps could be applied in any framework:
 
@@ -24,8 +88,10 @@ class ShopifyAuthController < ApplicationController
   def login
     shop = request.headers["Shop"]
 
+    # Builds the authorization URL route to redirect the user to
     auth_response = ShopifyAPI::Auth::Oauth.begin_auth(shop: domain, redirect_path: "/auth/callback")
 
+    # Store the authorization cookie
     cookies[auth_response[:cookie].name] = {
       expires: auth_response[:cookie].expires,
       secure: true,
@@ -33,26 +99,65 @@ class ShopifyAuthController < ApplicationController
       value: auth_response[:cookie].value
     }
 
+    # Redirect the user to "auth_response[:auth_route]" to allow user to grant the app permission
+    # This will lead the user to the Shopify Authorization page
     head 307
     response.set_header("Location", auth_response[:auth_route])
   end
 end
 ```
 
-## Add your OAuth callback route
+⚠️ You can see a concrete example in the `ShopifyApp` gem's [SessionController](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/sessions_controller.rb).
 
-After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `begin_auth`, above). Your app will now use the provided `validate_auth_callback` method to finalize the OAuth process. This method returns a hash containing the new session and a cookie to be set in the browser in form of {`session`: `ShopifyAPI::Auth::Session`, `cookie`: `ShopifyAPI::Auth::Oauth::SessionCookie`}.
+### 4. Handle OAuth Callback
+When the user grants permission to the app in Shopify admin, they'll be redirected back to the app's callback route
+(configured in [Step 2 - Add an OAuth callback route](#2-add-an-oauth-callback-route)).
+
+Use [`ShopifyAPI::AuthL::Oauth.validate_auth_callback`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/oauth.rb#L60) method to finalize the OAuth process.
+
+#### Input
+| Parameter    | Type    | Notes                                                                                                       |
+| ------------ | --------| ----------------------------------------------------------------------------------------------------------- |
+| `cookies`    | `Hash`  | All browser cookies in a hash format with key and value as `String` |
+| `auth_query` | `ShopifyAPI::Auth::Oauth::AuthQuery`| An `AuthQuery` containing the authorization request information used to validate the request.|
+
+#### Output
+This method returns a hash containing the new session and a cookie to be set in the browser in form of:
+```ruby
+{
+    session: ShopifyAPI::Auth::Session,
+    cookie: ShopifyAPI::Auth::Oauth::SessionCookie,
+}
+```
+| Key | Type | Notes |
+|-----|------|-------|
+|`session`|`ShopifyAPI::Auth::Session`|A session object that contains necessary information to identify the session like `shop`, `access_token`, `scope`, etc.|
+|`cookie` |`ShopifyAPI::Auth::Oauth::SessionCookie`|A session cookie to store on the user's browser. |
+
+#### Example
+Your app should call `validate_auth_callback` to construct the `Session` object and cookie that will be used later for authenticated API requests.
+
+1. Call `validate_auth_callback` to construct `Session` and `SessionCookie`.
+2. Update browser cookies with the new value for the session.
+3. Store the `Session` object to be used later when making authenticated API calls.
+   - See [Make a GraphQL API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md), or
+   [Make a REST API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md) for examples on how to use the result `Session` object.
 
 An example is shown below in a Rails app but these steps could be applied in any framework:
 
 ```ruby
 def callback
   begin
+    # Create an AuthQuery object from the request parameters,
+    # and pass the list of cookies to `validate_auth_callback`
     auth_result = ShopifyAPI::Auth::Oauth.validate_auth_callback(
       cookies: cookies.to_h,
-      auth_query: ShopifyAPI::Auth::Oauth::AuthQuery.new(request.parameters.symbolize_keys.except(:controller, :action))
+      auth_query: ShopifyAPI::Auth::Oauth::AuthQuery.new(
+        request.parameters.symbolize_keys.except(:controller, :action)
+      )
     )
 
+    # Update cookies with the authorized access token from result
     cookies[auth_result[:cookie].name] = {
       expires: auth_result[:cookie].expires,
       secure: true,
@@ -60,6 +165,10 @@ def callback
       value: auth_result[:cookie].value
     }
 
+    # Store the Session object if your app has a DB/file storage for session persistence
+    # This session object could be retrieved later to make authenticated API requests to Shopify
+    MyApp::SessionRepository.store_session(auth_result[:session])
+
     puts("OAuth complete! New access token: #{auth_result[:session].access_token}")
 
     head 307
@@ -70,35 +179,59 @@ def callback
   end
 end
 ```
-## Fetching sessions
 
-You can use the OAuth methods to create both offline and online sessions. Once the process is completed, the session will be stored as per your `Context.session_storage`, and can be retrieved with `SessionUtils` class methods.
+⚠️ You can see a concrete example in the `ShopifyApp` gem's [CallbackController](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/callback_controller.rb).
 
-- To load current session, you can use the following method:
+### 5. Using OAuth Session to make authenticated API calls
+Once your OAuth flow is complete, and you have stored your `Session` object from [Step 4 - Handle OAuth Callback](#4-handle-oauth-callback), you may use that `Session` object to make authenticated API calls.
 
+Example:
 ```ruby
-ShopifyAPI::Utils::SessionUtils.load_current_session(auth_header: <auth-header>, cookies: <cookies>, is_online: <true|false>)
-```
+def make_api_request(shop)
+  # 1. Retrieve the Session object stored from previous step
+  session = MyApp::SessionRepository.retrieve_session_for_shop(shop)
+
+  # 2. Create API client with the session information
+  # session must be type `ShopifyAPI::Auth::Session`
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new(session: session)
 
-Accepted arguments:
-| Parameter   | Type                      | Notes                                                                                                                                                                     |
-| ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth_header`   | `String`    | JWT token will be extracted from `auth_header` to load session for embedded apps. If JWT token is not provided this methods will try with `cookies`. Only required if trying to load, an embedded session. |
-| `cookies`   | `Hash(String, String)`    | The cookies from the HTTP request. A session cookie named `shopify_app_session` is used to load session for non-embedded apps. Can be omitted if loading and embedded session without falling back on cookies |
-| `is_online` | `Boolean`                 | Whether to load online or offline sessions. Defaults to `false` |
+  # 3. Use API client to make queries
+  response = graphql_client.query(query: MY_API_QUERY)
 
-This method will return a `ShopifyAPI::Auth::Session`  if a session exists. Either a proper token or a proper cookie must be present.
+  # 4. Use the response for your app
+  ...
+end
+```
 
-- To load offline session, you can use the following method:
+#### Setting `active_session`
+Alternatively, if you don't want to keep having to retrieve a Session object for a shop, you may set [`ShopifyAPI::Context.active_session`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/context.rb#L144).
+All of the API client classes will [use the `active_session`](https://github.com/Shopify/shopify-api-ruby/blob/c3bb9d8f8b6053756149a4cf9299e059ec337544/lib/shopify_api/clients/http_client.rb#L13) if the `session` passed in is `nil`.
 
+Example:
 ```ruby
-ShopifyAPI::Utils::SessionUtils.load_offline_session(shop)
-```
+#### Configuration
+def configure_app
+  # This method is called before making authenticated API calls
+  session = retrieve_session_from_file # your implementation of retrieving a session
+
+  # Activate session to be used in all API calls
+  # session must be type `ShopifyAPI::Auth::Session`
+  ShopifyAPI::Context.activate_session(session)
+
+end
+
+#### Using clients to make authenticated API calls
+def make_api_request
+  # 1. Create API client without session information
+  # The graphql_client will use `ShopifyAPI::Context.active_session` when making API calls
+  graphql_client = ShopifyAPI::Clients::Graphql::Admin.new
 
-Accepted arguments:
-| Parameter           | Type      | Notes                                                                                                                                                                     |
-| ------------------- | --------- | --------------------------------------------- |
-| `shop`              | `String`  | The shop url to find the offline session for. |
-| `include_expired`   | `Boolean` | Include expired sessions or not.              |
+  # 2. Use API client to make queries
+  ...
+end
+
+```
 
-This method will return a `ShopifyAPI::Auth::Session` if a session exists and `nil` otherwise. This method **does not** perform any validation on the shop domain, so it **must not** rely on user input for the domain. This method is typically meant to be used in background tasks like webhooks, where the data is expected to have been validated when the task was enqueued.
+⚠️ See following docs on how to use the API clients:
+- [Make a GraphQL API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/graphql.md)
+- [Make a REST API call](https://github.com/Shopify/shopify-api-ruby/blob/main/docs/usage/rest.md)