Skip to content

rest.md

Latest commit

 

History

History
286 lines (224 loc) · 13.8 KB

rest.md

File metadata and controls

286 lines (224 loc) · 13.8 KB

Make a REST API call

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.

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:

There are 2 methods you can use to make REST API calls to Shopify:

  • Using REST Resources

    • Resource classes with similar syntax as ActiveResource, and follows our REST convention. Example:
    # Update product title
product = ShopifyAPI::Product.find(id: <product_id>)
product.title = "My awesome product"
product.save!

  • Using REST Admin Client

    • More manual input method to make the API call. Example:
    # 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.

The version of REST resource that's loaded and used is set from ShopifyAPI::Context.setup

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.

When nil is passed in, active session information is inferred from ShopifyAPI::Context.active_session.
To set active session, use ShopifyAPI::Context.activate_session.

This is handled automatically behind the scenes if you use ShopifyApp's session controllers.
from_hash Hash Default value is nil. Sets the resource properties to the values provided from the hash.

Examples:

# 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.

Usage Examples

⚠️ Reference documentation on shopify.dev contains more examples on how to use each REST Resources.

# Find and update a customer email
customer = ShopifyAPI::Customer.find(id: customer_id)
customer.email = "steve-lastnameson@example.com"
customer.save!

# Create a new product from hash
product_properties = {
  title: "My awesome product"
}
product = ShopifyAPI::Product.new(from_hash: product_properties)
product.save!

# Create a product manually
product = ShopifyAPI::Product.new
product.title = "Another one"
product.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, e.g.:

Using REST Admin Client

Instantiation

Create an instance of ShopifyAPI::Clients::Rest::Admin using the current session to make requests to the Admin API.

Constructor parameters

Parameter Type Notes
session ShopifyAPI::Auth::Session Default value is nil.

When nil is passed in, active session information is inferred from ShopifyAPI::Context.active_session.
To set active session, use ShopifyAPI::Context.activate_session.

This is handled automatically behind the scenes if you use ShopifyApp's session controllers.
api_version String Default value is nil. When nil is passed in, api version is inferred from ShopifyAPI::Context.setup.

Examples:

# 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

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
path String all none The requested API endpoint path. This can be one of two formats:
  • The path starting after the /admin/api/{version}/ prefix, such as products, which executes /admin/api/{version}/products.json
  • The full path, such as /admin/oauth/access_scopes.json
body Hash(any(Symbol, String), untyped) put, post none The body of the request
query Hash(any(Symbol, String), any(String, Integer, Float)) none none An optional query object to be appended to the request url as a query string
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 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 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
next_page_info String See Pagination
Failure

If the request has failed, an error will be raised describing what went wrong. You can rescue ShopifyAPI::Errors::HttpResponseError and output error messages with errors.full_messages

See example:

    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

# Create a new client.
client = ShopifyAPI::Clients::Rest::Admin.new(session: session)

# Use `client.get` to request the specified Shopify REST API endpoint, in this case `products`.
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.

Perform a POST request

# Create a new client.
client = ShopifyAPI::Clients::Rest::Admin.new(session: session)

# Build your post request body.
body = {
  product: {
    title: "Burton Custom Freestyle 151",
    body_html: "\u003cstrong\u003eGood snowboard!\u003c\/strong\u003e",
    vendor: "Burton",
    product_type: "Snowboard",
  }
}

# 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.

Perform a PUT request

# Create a new client.
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.
# This will update product title for product with ID <id>
client.put(path: "products/<id>.json", body: body)

For more information on the products endpoint, check out our API reference guide.

Pagination

This library also supports cursor-based pagination for REST Admin API requests. Learn more about REST request pagination.

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:

client = ShopifyAPI::Clients::Rest::Admin.new(session: session)

response = client.get(path: "products", query: { limit: 10 })
next_page_info = response.next_page_info

if next_page_info
  next_page_response =client.get(path: "products", query: { limit: 10, page_info: next_page_info })
  some_function(next_page_response)
end

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.

An example of this is shown below:

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