How do these two patterns differ, with regards to API design?

I am learning API design, and based on the blog I am reading

GET http://www.nowhere.com/images/getImage?imageId=123

is an antipattern, and should be avoided.

while the blog does not mention this, I guess the preferred method would be

GET http://www.nowhere.com/images/123

How is the second method the preferred method? what exactly is wrong/limitation with the first method?

> How is the second method the preferred method? what exactly is wrong/limitation with the first method?

Both spellings, as far as REST is concerned, are fine; REST doesn't care what spelling conventions you use for your resource identifiers.

The first variation is more convenient when you are trying to integrate with HTML forms. The second variation is more convenient when you want to use relative references.

There is a bias among designers against the first spelling, because it has the appearance of reflecting a misunderstanding of how resource models work in HTTP.

GET /images/123

Is closely analogous to this psuedo code

resouce("/images/123").get()

Similarly

GET /images/getImage?imageId=123

is analogous to

resource("/images/getImage?imageId=123").get()

Contrast this with:

resource("/images").getImage(imageId=123)

Expressed another way: the resource identifier is the identifier of the document that you are fetching, which you might think of as the name of the document.

So the argument is about whether "getImage" (a verb phrase) makes a good name for a document (noun), in much the same way that you might get push back in a code review were you to propose "getImage" as a variable name that holds a reference to a data structure.

Much like variable names in code, the machines don't care, either spelling will work just fine. But we see resource identifiers (in browser location controls, browser histories, bookmark lists, access logs, etc) a lot more frequently than we do variable names, so it is more important that they are easy for humans to work with.