phpandroidhttpslim

Specifing parameters in REST API GET request


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.


Solution

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