Specifing parameters in REST API GET request

Question

I want to have the ability to specify the image size of a product in ONE request, I have different ideas about this, here they are:

mysuperstore.com/api/categories/40/products/53?width=100&height=100

I think this is bad practice, because it is unclear what does width and height mean, maybe there is physical size of product.

Another variant is:

mysuperstore.com/api/categories/40/products/53/image?width=100&height=100

It looks pretty good, but I have to make two requests in this case, it seems like it is another resource id (image).

First request is for product

  mysuperstore.com/api/categories/40/products/53/

Second one is for image URL

mysuperstore.com/api/categories/40/products/53/image?width=100&height=100

Yes, I need not to return raw image (data), but just URL.
I am creating API on PHP server using Slim Framework. I found an example of such API request with optional parameters

$app->get('/archive(/:year(/:month(/:day)))', function ($year = 2010, $month = 12, $day = 05) use ($app) {
    echo sprintf('%s-%s-%s', $year, $month, $day);
    print_r($app->request()->get());
});

So the previous URL will match this example and I can pass all required parameters in one request.

So my questions is if it is a good practice to do so, maybe this URL can be confusable for someone not familiar with API.

  mysuperstore.com/api/categories/40/products/53/image?width=100&height=100

So I am asking someone more experienced in this than me, my goal is to create API that can be understand clearly without reading tons of API documentation. And my API should follow all best practices.

That's why I am asking this question, I hope someone can help me in this.

Answer 1

我会这样做：

mysuperstore.com/api/categories/40/products/53/?image[width]=100&image[height]=100

Answer 2

I think its not related to SLIM framework but more a design implementation question. You can always check this guide on API design best practice.

For your question about image in particular, you can follow apple or google guideline, they are using image_name[WIDTH]x[HEIGHT].jpeg , ex :

http://a4.mzstatic.com/us/r30/Purple7/v4/c2/36/25/c2362536-f6fc-4ef6-2a03-9b899ca00af9/screen480x480.jpeg

Images are pre-generated and available on CDN. Depending on how many calls you will have to handle but generating new images on the fly can be very load consuming. At least you should store/cache already generated images.