Versioning URI format is non-standard?

[DigitalOrchard]

Shopify is great, and provides really good software, but it concerns me when a company announces something new, only to have approached it from a bizarre angle. There are established best practices for API design, and I'm not sure that Shopify's approach follows this.

Your new URL format is:

• https://{shop}.myshopify.com/admin/api/{version}/{endpoint}.json

First, this was flawed from the very beginning by attaching API requests to the same hostname as the entire storefront. Instead, if you had a parallel setup, it gives you the opportunity to distribute load across hosts.

For example, you could have introduced this format:

• https://{shop}.api.myshopify.com/{version}/admin/{endpoint}.json

1. The "api" is incorporated into the hostname instead of the URI.
2. The {version} comes ahead of the endpoint URI.

For example, the "endpoint" is technically "/admin/products.json", not just "products.json", because you could have a products endpoint in several scopes, therefore the scope defines the full endpoint for that resource.

Oh well. What's done is done.

[Evan_Huus · Accepted solution]

Hi, I’m happy to provide a bit of clarification. While there are definitely cons to the approach we took, the trade-offs we made were very deliberate:

• Attaching API requests to the same hostname as the storefront doesn’t actually affect our ability to load-balance internally. I’m not sure what assumptions you’re making about our set-up, but we already do distribute API and storefront load across hosts.
• Putting the version after the /admin/ was a deliberate choice to capture the fact that this versioning scheme is specific to our Admin API. As mentioned in the announcement blog post, some of our other APIs are not yet versioned.

[DigitalOrchard · Accepted solution]

Thanks for your response. Glad to hear that requirements like load-balancing are accounted for.

I currently use Shopify POS to run my small business and still find some requests during the checkout phase to be much slower than they need to be. I build web applications, with a heavy focus on performance, so I know the checkout could be faster. So I ask myself - "are they overburdening their systems and that's causing the slowdown?". Maybe it was an assumption, but I when I look at the versioned API URL design, it added weight to my theory. As a developer, I take a heavily-distributed approach from the onset to avoid the need to layer on load-balancing on top of the application. Requests are handled by smaller purposeful hosts, and I was hoping that was designed into updated Shopify's API.

Regarding the location of the version, I understand your reason, but you also need to understand that REST is designed around URIs that point to specific resources. You have deviated slightly from that by calling just the segment(s) of the URI *after* the version segment the endpoint. Technically, the /admin/ is also part of the resource URI since it belongs with the /product segment. There could be multiple product-type resources, and therefore the /admin gives scope. However, now the version number splits those segments up, suggesting each version of a product is a different resource? Your design just complicates the URI more than it needed to be. That's all.

Thanks for your hard work nonetheless. 🙂