Merge pull request #974 from Shopify/update-rest-resource-guide

Update REST Resource Guide

.changeset/brave-knives-raise.md

@@ -0,0 +1,2 @@
+---
+---

docs/guides/rest-resources.md

@@ -8,8 +8,38 @@ To make it easier to interact with the API, this library provides resource class
 > **Note**: we provide auto-generated resources for all **_stable_** API versions.
 > If your app is using `unstable` or a Release Candidate, you can still import REST resources (see [mounting REST resources](#mounting-rest-resources) below) for other versions, but we'll log a warning to remind you to update when you're ready.
 
+## Resource Methods
+
+| Resource Method | Description | Admin API endpoint | Return |
+| --------------- | ----------- | ------------------ | ------ |
+| `find` | Fetch a single resource by its ID | `GET /admin/api/{version}/{resource_name}/{resource_id}.json` | A single resource |
+| `all` | Fetch all resources of a given type | `GET /admin/api/{version}/{resource_name}.json` | [An array of resources](#all-return-value) |
+| `count` | Fetch the number of resources of a given type | `GET /admin/api/{version}/{resource_name}/count.json` | Integer |
+| `save` | If the primary key for the resource **is not set**, a new resource will be created in Shopify | `POST /admin/api/{version}/{resource_name}.json` | void Promise (If option update: true is passed, the resource will be updated with the returned data.) |
+| `save` | If the primary key for a resource **is set** the resource in Shopify will be updated  | `PUT /admin/api/{version}/{resource_name}/{resource_id}.json` | Promise void (If option update: true is passed, the resource will be updated with the returned data.) |
+| `delete` | Delete an existing resource | `DELETE /admin/api/{version}/{resource_name}/{resource_id}.json` | void Promise |
+
+Some resources will have additional methods to help with common interactions, such as the [orders method on the customer resource](https://shopify.dev/docs/api/admin-rest/2023-07/resources/customer#get-customers-customer-id-orders). Review the [REST API reference](https://shopify.dev/docs/api/admin-rest) documentation for more information.
+
+### All Return Value
+The all method will return an array of resources, along with the response headers and pagination information.
+
+```
+FindAllResponse<T = Base> {
+    data: T[];
+    headers: Headers;
+    pageInfo?: PageInfo;
+}
+```
+
+Please visit our [REST API reference documentation](https://shopify.dev/docs/api/admin-rest) for detailed instructions on how to call each of the endpoints.
+
+## Example Usage
+
 Below is an example of how REST resources can make it easier to fetch the first product and update it:
 
+### Update a Resource
+
 <div>With a plain REST client:
 
 ```ts
@@ -69,21 +99,63 @@ const product = await shopify.rest.Product.find({session, id: '7504536535062'});
 
 product.title = 'A new title';
 
+// After promise resolves, the product will be updated with the returned data
 await product.save({
   update: true,
 });
 ```
 
 </div>
 
-The resource classes provide representations of all endpoints for the API resource they cover. A few examples:
+### Create a resource
 
-1. `GET /products/{product_id}.json` maps to `Product.find()`
-1. `POST /products.json` maps to `product.save()` (as an instance method)
-1. `GET /products.json` maps to `Product.all()`
-1. `GET /products/count.json` maps to `Product.count()`
+```ts
 
-Please visit our [REST API reference documentation](https://shopify.dev/docs/api/admin-rest) for detailed instructions on how to call each of the endpoints.
+const product = new shopify.rest.Product({session: session});
+product.title = "Burton Custom Freestyle 151";
+product.body_html = "<strong>Good snowboard!</strong>";
+product.vendor = "Burton";
+product.product_type = "Snowboard";
+product.status = "draft";
+
+// After promise resolves, product will be updated with the returned data
+await product.save({
+  update: true,
+});
+```
+
+### Get a resource
+
+```ts
+// Session is built by the OAuth process
+
+const product = await shopify.rest.Product.find({
+  session: session,
+  id: 632910392,
+});
+
+console.log(product);
+```
+
+### Get all resources
+
+```ts
+// Session is built by the OAuth process
+
+const products = await shopify.rest.Product.all({
+  session: session,
+});
+
+// The list of products
+console.log(products.data);
+
+// The pagination information
+console.log(products.pageInfo);
+
+// The response headers
+console.log(products.headers);
+
+```
 
 ## Mounting REST resources