shopify_api 13.0.0 → 14.0.0

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)

data/docs/usage/rest.md

@@ -1,10 +1,206 @@
 # Make a REST API call
 
-Once OAuth is complete, we can use the `ShopifyAPI::Clients::Rest::Admin` client to make an API call to the Shopify Admin API. To do this, you can create an instance of `ShopifyAPI::Clients::Rest::Admin` using the current session to make requests to the Admin API.
+Once OAuth is complete, we can use `ShopifyAPI`'s REST library to make authenticated API calls to the Shopify Admin 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.
+
+#### There are 2 methods you can use to make REST API calls to Shopify:
+- [Using REST Resources](#using-rest-resources)
+  - Resource classes with similar syntax as `ActiveResource`, and follows our REST convention. Example:
+  ``` ruby
+  # Update product title
+  product = ShopifyAPI::Product.find(id: <product_id>)
+  product.title = "My awesome product"
+  product.save!
+  ```
+
+- [Using REST Admin Client](#using-rest-admin-client)
+  - More manual input method to make the API call. Example:
+  ```ruby
+  # Create a new client.
+  rest_client = ShopifyAPI::Clients::Rest::Admin.new
+
+  # Update product title
+  body = {
+    product: {
+      title: "My cool product"
+    }
+  }
+
+  # Use `client.put` to send your request to the specified Shopify Admin REST API endpoint.
+  rest_client.put(path: "products/<id>.json", body: body)
+  ```
+
+## Using REST Resources
+We provide a templated class library to access REST resources similar to `ActiveResource`. Format of the methods closely resemble our [REST API schema](https://shopify.dev/docs/api/admin-rest).
+
+The version of REST resource that's loaded and used is set from [`ShopifyAPI::Context.setup`](https://github.com/Shopify/shopify-api-ruby/blob/main/README.md#setup-shopify-context)
+
+### Instantiation
+Create an instance of the REST resource you'd like to use and optionally provide the following parameters.
+#### 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). |
+| `from_hash` | `Hash` |  Default value is `nil`. Sets the resource properties to the values provided from the hash. |
+
+Examples:
+
+```ruby
+# To construct an Orders object using default session
+# This creates a new order object with properties provided from the hash
+order = ShopifyAPI::Orders.new(from_hash: {property: value})
+order.save!
+```
+
+### Methods
+Typical methods provided for each resources are:
+- `find`
+- `delete`
+- `all`
+- `count`
+
+Full list of methods can be found on each of the resource class.
+- Path:
+  - https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/rest/resources/#{version}/#{resource}.rb
+- Example for `Order` resource on `2024-01` version:
+  - https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/rest/resources/2024_01/order.rb
+
+### The `save` method
+
+The `save` or `save!` method on a resource allows you to `create` or `update` that resource.
+
+#### Create a new resource
+
+To create a new resource using the `save` or `save!` method, you can initialize the resource with a hash of values or simply assigning them manually. For example:
+
+```Ruby
+# Create a new product from hash
+product_properties = {
+  title: "My awesome product"
+}
+product = ShopifyAPI::Product.new(from_hash: product_properties)
+product.save!
+
+# Create a new product manually
+product = ShopifyAPI::Product.new
+product.title = "Another one"
+product.save!
+```
+
+#### Update an existing resource
+
+To update an existing resource using the `save` or `save!` method, you'll need to fetch the resource from Shopify first. Then, you can manually assign new values to the resource before calling `save` or `save!`. For example:
+
+```Ruby
+# Update a product's title
+product = ShopifyAPI::Product.find(id: product_id)
+product.title = "My new title"
+product.save!
+
+# Remove a line item from a draft order
+draft_order = ShopifyAPI::DraftOrder.find(id: draft_order_id)
+
+new_line_items = draft_order.line_items.reject { |line_item| line_item["id"] == 12345 }
+draft_order.line_items = new_line_items
+
+draft_order.save!
+```
+
+> [!IMPORTANT]
+> If you need to unset an existing value,
+> please explicitly set that attribute to `nil` or empty values such as `[]` or `{}`. For example:
+>
+> ```Ruby
+>   # Removes shipping address from draft_order
+>   draft_order.shipping_address = {}
+>   draft_order.save!
+> ```
+>
+> This is because only modified values are sent to the API, so if `shipping_address` is not "modified" to `{}`. It won't be part of the PUT request payload
+
+When updating a resource, only the modified attributes, the resource's primary key, and required parameters are sent to the API. The primary key is usually the `id` attribute of the resource, but it can vary if the `primary_key` method is overwritten in the resource's class. The required parameters are identified using the path parameters of the `PUT` endpoint of the resource.
+
+### Headers
+You can add custom headers to the HTTP calls made by methods like `find`, `delete`, `all`, `count`
+by setting the `headers` attribute on the `ShopifyAPI::Rest::Base` class in an initializer, like so:
+
+```ruby
+ShopifyAPI::Rest::Base.headers = { "X-Custom-Header" => "Custom Value" }
+# `find` will call the API endpoint with the custom header
+ShopifyAPI::Customer.find(id: customer_id)
+```
+
+### Usage Examples
+⚠️ The [API reference documentation](https://shopify.dev/docs/api/admin-rest) contains more examples on how to use each REST Resources.
+
+```Ruby
+# Find and update a customer email
+customer = ShopifyAPI::Customer.find(id: customer_id)
+customer.email = "steve-lastnameson@example.com"
+customer.save!
+
+# Get all orders
+orders = ShopifyAPI::Orders.all
+
+# Retrieve a specific fulfillment order
+fulfillment_order_id = 123456789
+fulfillment_order = ShopifyAPI::FulfillmentOrder.find(id: fulfillment_order_id)
+
+# Remove an existing product image
+product_id = 1234567
+image_id = 1233211234567
+ShopifyAPI::Image.delete(product_id: product_id, id: image_id)
+```
+
+More examples can be found in each resource's documentation on [shopify.dev](https://shopify.dev/docs/api/admin-rest), e.g.:
+- [Order](https://shopify.dev/docs/api/admin-rest/current/resources/order)
+- [Product](https://shopify.dev/docs/api/admin-rest/current/resources/product)
+
+## Using REST Admin Client
+
+### Instantiation
+Create an instance of [`ShopifyAPI::Clients::Rest::Admin`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/clients/rest/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).|
+
+Examples:
+```ruby
+# Create a default client with `ShopifyAPI::Context.api_version`
+# and the active session from `ShopifyAPI::Context.active_session`
+client = ShopifyAPI::Clients::Rest::Admin.new
+
+# Create a client with a specific session "my_session"
+client = ShopifyAPI::Clients::Rest::Admin.new(session: my_session)
+
+# Create a client with active session from `ShopifyAPI::Context.active_session`
+# and a specific api_version - "unstable"
+client = ShopifyAPI::Clients::Rest::Admin.new(api_version: "unstable")
+
+# Create a client with a specific session "my_session" and api_version "unstable"
+client = ShopifyAPI::Clients::Rest::Admin.new(session: my_session, api_version: "unstable")
+```
 
-## Methods
+### Methods
 
-The Rest Admin client offers the 4 core request methods: `get`, `delete`, `post`, and `put`. These methods each take the parameters outlined in the table below. If the request is successful these methods will all return a `ShopifyAPI::Clients::HttpResponse` object, which has properties `code`, `headers`, and `body` otherwise an error will be raised describing what went wrong.
+The `ShopifyAPI::Clients::Rest::Admin` client offers the 4 core request methods:
+- `get`
+- `delete`
+- `post`
+- `put`
+
+#### Input Parameters
+
+Each method can take the parameters outlined in the table below.
 
 | Parameter      | Type                                                     | Required in Methods | Default Value | Notes                                                                                                                                                                                                                                                                                  |
 | -------------- | -------------------------------------------------------- | :-----------------: | :-----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -14,16 +210,40 @@ The Rest Admin client offers the 4 core request methods: `get`, `delete`, `post`
 | `extraHeaders` | `Hash(any(Symbol, String), any(String, Integer, Float))` |        none         |     none      | Any additional headers you want to send with your request                                                                                                                                                                                                                              |
 | `tries`        | `Integer`                                                |        None         |      `1`      | The maximum number of times to try the request _(must be >= 0)_                                                                                                                                                                                                                        |
 
-**Note:** _These paramaters can still be used in all methods regardless of if they are required._
+**Note:** _These parameters can still be used in all methods regardless of if they are required._
+
+#### 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)|
 
-## Usage Examples:
+##### 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`
 
-### Perform a `GET` request:
+See example:
 
 ```ruby
-# Load the current session to get the `accessToken`.
-session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+    client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
+    response = client.get(path: "NOT-REAL")
+    some_function(response.body)
+rescue ShopifyAPI::Errors::HttpResponseError => e
+  puts fulfillment.errors.full_messages
+  # {"errors"=>"Not Found"}
+  # If you report this error, please include this id: bce76672-40c6-4047-b598-46208ab076f0.
+```
+### Usage Examples
+
+#### Perform a `GET` request
 
+```ruby
 # Create a new client.
 client = ShopifyAPI::Clients::Rest::Admin.new(session: session)
 
@@ -33,13 +253,11 @@ response = client.get(path: "products")
 # Do something with the returned data
 some_function(response.body)
 ```
+_For more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/docs/api/admin-rest/latest/resources/product)._
 
-### Perform a `POST` request:
+#### 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)
 
@@ -54,64 +272,59 @@ body = {
 }
 
 # Use `client.post` to send your request to the specified Shopify Admin REST API endpoint.
+# This POST request will create a new product.
 client.post({
   path: "products",
   body: body,
 });
 ```
 
-_for more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/docs/api/admin-rest/unstable/resources/product)._
+_For more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/docs/api/admin-rest/latest/resources/product)._
 
-### Override the `api_version`:
+#### Perform a `PUT` request
+  ```ruby
+  # Create a new client.
+  client = ShopifyAPI::Clients::Rest::Admin.new
 
-```ruby
-# To experiment with prerelease features, pass the api_version "unstable".
-client = ShopifyAPI::Clients::Rest::Admin.new(session: session, api_version: "unstable")
-```
+  # Update product title
+  body = {
+    product: {
+      title: "My cool product"
+    }
+  }
 
-## Pagination
+  # Use `client.put` to send your request to the specified Shopify Admin REST API endpoint.
+  # This will update product title for product with ID <id>
+  client.put(path: "products/<id>.json", body: body)
+```
 
-This library also supports cursor-based pagination for REST Admin API requests. [Learn more about REST request pagination](https://shopify.dev/docs/api/usage/pagination-rest).
+_For more information on the `products` endpoint, [check out our API reference guide](https://shopify.dev/docs/api/admin-rest/latest/resources/product)._
 
-After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and passed as the page_info query param in other requests.
+#### Accessing Rate Limit information
 
-An example of this is shown below:
+The REST resources have `api_call_limit` and `retry_after` can be found on the Resource class. These values correspond to the `X-Shopify-Shop-Api-Call-Limit` and `Retry-After` [headers](https://shopify.dev/docs/api/usage/rate-limits#rest-admin-api-rate-limits) respectively.
 
 ```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 })
-
-loop do
-  some_function(response.body)
-  break unless response.next_page_info
-  response =  client.get(path: "products", query: { limit: 10, page_info: response.next_page_info })
-end
-```
+product = ShopifyAPI::Product.find(session: session, id: 12345)
 
-Similarly, when using REST resources the `next_page_info` and `prev_page_info` can be found on the Resource class and passed as the page_info query param in other requests.
+# X-Shopify-Shop-Api-Call-Limit: 32/40
+request_count = ShopifyAPI::Product.api_call_limit[:request_count] # 32
+bucket_size = ShopifyAPI::Product.api_call_limit[:bucket_size] # 40
 
-An example of this is shown below:
+retry_after = ShopifyAPI::Product.retry_request_after
 
-```ruby
-session = ShopifyAPI::Utils::SessionUtils.load_current_session(headers, cookies, is_online)
+```
 
-products = ShopifyAPI::Product.all(session: session, limit: 10)
+### Pagination
 
-loop do
-  some_function(products)
-  break unless ShopifyAPI::Product.next_page?
-  products = ShopifyAPI::Product.all(session: session, limit: 10, page_info: ShopifyAPI::Product.next_page_info)
-end
-```
+This library also supports cursor-based pagination for REST Admin API requests. [Learn more about REST request pagination](https://shopify.dev/docs/api/usage/pagination-rest).
 
-The next/previous page_info strings can also be retrieved from the response object and added to a request query to retrieve the next/previous pages.
+#### REST Admin Client
+After making a request, the `next_page_info` and `prev_page_info` can be found on the response object and passed as the `page_info` query param in other requests.
 
 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 })
@@ -123,22 +336,19 @@ if next_page_info
 end
 ```
 
-### Error Messages
-
-You can rescue `ShopifyAPI::Errors::HttpResponseError` and output error messages with `errors.full_messages`
+#### REST Resource
+Similarly, when using REST resources the `next_page_info` and `prev_page_info` can be found on the Resource class and passed as the `page_info` query param in other requests.
 
-See example:
+An example of this is shown below:
 
 ```ruby
- fulfillment = ShopifyAPI::Fulfillment.new(session: @session)
-  fulfillment.order_id = 2776493818000
-  ...
-  fulfillment.tracking_company = "Jack Black's Pack, Stack and Track"
-  fulfillment.save()
-rescue ShopifyAPI::Errors::HttpResponseError => e
-  puts fulfillment.errors.full_messages
-  # {"base"=>["Line items are already fulfilled"]}
-  # If you report this error, please include this id: e712dde0-1270-4258-8cdb-d198792c917e.
+products = ShopifyAPI::Product.all(session: session, limit: 10)
+
+loop do
+  some_function(products)
+  break unless ShopifyAPI::Product.next_page?
+  products = ShopifyAPI::Product.all(session: session, limit: 10, page_info: ShopifyAPI::Product.next_page_info)
+end
 ```
 
 [Back to guide index](../README.md)