Learning the Foxycart Hypermedia API

Hey guys,

I'm scoping out a couple Foxycart API integration projects, but I'm not a developer, so I'm trying to learn the basics of APIs. I wanted to poke around the Foxycart API to understand the various data points and structure.

I see the the HAL browser here: https://api-sandbox.foxycart.com/hal-browser/browser.html#/

I also heard of the Postman tool: https://www.getpostman.com/

Are these tools essentially doing the same thing? Curious how they may fit into the API integration development process.

Thanks.
Comments
  • brettbrett FoxyCart Team
    Hey @Epotratz. Great question. The HAL Browser's just a handy way to explore things sort of "at a glance". @luke or @fc_adam may have different opinions, but personally I just use that as a sort of quick sanity check sometimes.

    Postman, otoh, I use pretty extensively when I'm developing (not just with our API but with pretty much any API). It's super easy to use once you understand the basics of HTTP requests, and it's just so handy for figuring out what you want to do before you actually start writing the code. Is it the same thing as the HAL Browser? In a sense, but much more powerful and customizable. And you can have multiple tabs, save header sets, save tab sets, etc. Tbh once I got familiar with Postman, I probably stopped using the HAL browser much at all.

    Does that get you a bit more info?
  • EpotratzEpotratz Member
    edited October 5
    @brett

    Thanks for that. Makes sense.

    We are actually working to bring our API integrations into Dsync, for Foxycart and other cloud apps we use. Dsync is one of the emerging integration platform as a service (iPaaS) solutions. It's similar to Built.io Flow, Tray.io, and Azuqua but more affordable, and significantly more powerful than beginner solutions like Zapier or IFTTT.

    I've read all of @luke 's articles on the Hypermedia API. I'm actually wondering if the Hypermedia aspect would be a hindrance or help in connecting to an iPaaS platform. Do you guys have any thoughts on connecting Foxycart with iPaaS platforms? And would you be interested in building a Foxycart connector for Dsync?

  • @brett

    I notice in the datafeed documentation it has:
    customer_first_name
    customer_last_name
    shipping_first_name
    shipping_last_name
    etc.,...

    But I see different fields in the Hypermedia API, such as:
    first_name
    last_name
    is_default_shipping (If YES, then these are the "shipping" names?)
    etc.

    We need to get the most current customer "Shipping" details into our email marketing platform for the customer profile. (In our experience, the shipping-name is a more likely match to the email than the billing-name). Should we be trying to pull this customer info out of the datafeed for each transaction, or the API? Any thoughts?

    And if customer info in Foxycart is updated by an API call, is there anyway to trigger a webhook/datafeed from Foxycart for this change? (To push this updated info to our email marketing platform)

    FYI, we are trying to maximize the use of webhooks to keep things updated in "real-time" and avoid excess polling.

  • fc_adamfc_adam FoxyCart Team
    @Epotratz,

    Good question. The data structure in our XML datafeed will be different than what you see in the Hypermedia API, which is much newer than the datafeed. We're finalising a new webhook feature which will more closely match the hAPI structure as well (along with JSON formatting, automatic retries and other cool stuff).

    In terms of whether you should use the datafeed or the API - at the time of the transaction, the datafeed and the API should be identical - so either is fine. The API will always return the most up to date version of the information though - where as the datafeed will be the information as it was at the time of the transaction - so it depends on your specific needs as to which to use.
    And if customer info in Foxycart is updated by an API call, is there anyway to trigger a webhook/datafeed from Foxycart for this change? (To push this updated info to our email marketing platform)
    Not currently - but that is something we're working towards with our new webhook functionality too.
  • @fc_adam

    Interesting about the new webhook feature(s)! How close is this? (We're looking to start our integration development in the next couple weeks)

    Also, our customer service agents we'll be making some adjustments to subscription status (deactivating/reactivating) through the Foxy API. Is there a "timestamp" or "modified stamp" in the Foxy API for changes that have been made? (We want to sync timestamped events to our marketing platform Klaviyo)

    Thanks guys.

  • fc_adamfc_adam FoxyCart Team
    @Epotratz,

    We are getting close - working through final changes and testing currently. We don't have an ETA at this point, but we're pretty excited to get it live.
    Also, our customer service agents we'll be making some adjustments to subscription status (deactivating/reactivating) through the Foxy API. Is there a "timestamp" or "modified stamp" in the Foxy API for changes that have been made? (We want to sync timestamped events to our marketing platform Klaviyo)
    Good question. I know we had a ticket related to the modified timestamps for API elements. We'll check on the status of that and someone will follow up.
  • @fc_adam

    Ok, I'll keep an eye in the Changelog for the new Datafeed updates.

    BTW, I'm assuming existing integrations that are expecting the current (old) datafeed format may break from this update?
  • fc_adamfc_adam FoxyCart Team
    edited October 14
    @Epotratz,

    The existing XML datafeed format will be sticking around too - so any existing integrations will continue to work fine.

    In terms of the modified timestamps - I've confirmed with the team that any hAPI initiated changes will update the corresponding modified timestamps, but currently changes implemented outside of the hAPI (such as with the legacy API), won't update those timestamps yet.
  • Hey @fc_adam ,

    I'm browsing around in the Postman API tool looking at our "subscriptions", "transaction templates", and "items". (trying to define the requirements for an integration)

    e.g.,
    https://api.foxycart.com/subscriptions/371480
    https://api.foxycart.com/carts/1324521551
    https://api.foxycart.com/carts/1324521551/items

    However, I notice that none of the items in the subscription transaction templates show any "discount" values in the below fields, despite our use of category discounts and coupon codes:


    image



    ((image from hal browser))

    When exactly would the "discount_name", "discount_type", and "discount_details" be populated?

    FYI, I do see that when I drill down into Discounts for this Cart, Coupon Codes applied to this Cart, or Item Options for This Item that I see the details on the discounts/coupons.


    And if I'm telling a developer that I want to capture the item name value for a subscription, I can see that this needs to come from the "subscription transaction template", but what exactly is the "path" to describe this field? (e.g., https://api.foxycart.com/carts/1324521551/items/name or ?)
  • lukeluke FoxyCart Team
    Hello @Epotratz.

    What you're seeing there is a line item discount: https://wiki.foxycart.com/v/2.0/coupons_and_discounts#product_discount

    It's specific to that individual item. That's different from a category discount or a coupon discount. Both line item and category discounts will create item options which include a price modifier.

    Yes, the subscription itself doesn't have a name as it may contain multiple items which could change over time. You can zoom in on the transaction_template from a subscription: https://api.foxycart.com/rels/subscription and include a further zoom on the transaction template items.

    There is no path for the name, but the item resource has a name property to describe the item: https://api.foxycart.com/rels/items So you'd get the whole item JSON and parse it to get the name. If you want to filter by a specific name, you can use the filtering and zooming described here: https://api.foxycart.com/docs/cheat-sheet

    I'm not sure if this is helpful to visual the path of the link relationships for drilling down to the resources you want, but it may be: https://api-sandbox.foxycart.com/hal-browser/index.html

    Please let us know if that answers your questions.
  • EpotratzEpotratz Member
    edited October 20
    @luke

    Makes sense on the line-item discount.

    Regarding the "path" question, I'm creating a spreadsheet mapping all the Foxycart API fields to the Klaviyo API fields for our integration. Your mentioned the resource https://api.foxycart.com/rels/items, but it doesn't specify the item name in a "subscription transaction template". What is the most helpful way to communicate this to a developer?

    And another amatuer question...

    In Postman, for my OAuth 2.0 new access token request, I generated a token in the Foxycart Admin, and then input the following values based on what I found in the Foxy API cheatsheet and the Foxy OAuth for 3rd Party Integrations page:

    https://drive.google.com/file/d/0B0JY4Srbo9pLZWlJUUQ0OWwzMHM/view

    Then I tried logging in with my admin credentials, and I keep getting this error in Postman:

    "Error: The redirect URI provided is missing or does not match"

    I'm assuming something is wrong with my Callback URL/redirect URI? (I copied my Client ID and abc123 'state' in there)

    Thanks in advance.

  • I also tried using https://www.getpostman.com/oauth2/callback as the callback URL, but that is giving me the same error.
  • @luke

    To follow up on my "path" question;

    In the Foxy API docs, and in this video where you discuss interactive link relationships, you talk about "not coding directly to the url" and instead "coding to link relationships". How do I write out the link relationships I want to a developer?

    Something like this?

    fx:store > fx:subscriptions > fx:example_entry > fx:transaction_template > fx:items | name

  • EpotratzEpotratz Member
    edited October 24
    Hey guys,

    Any idea how to get new access tokens working in Postman?

    Or is it normal to generate a new Token in the Foxycart admin every two hours ??

  • fc_adamfc_adam FoxyCart Team
    @Epotratz,

    Good question. Brett's had the most experience with Postman on our side - he's going to write up some instructions on using that to work with the hAPI soon which should help with how best to approach that.
Sign In or Register to comment.