Frustrated by Magento? Then you’ll love
I’m writing this down so I can remember it later – if you’re not deep into Magento service contracts apologies for the word soup.
When Magento’s parsing doc block’s for parameter types, it’s only looking at interfaces – or possibly its only looking at the type it knows about. i.e. if you have something like this
<route url="/V1/pulsestorm_apitest2/things/:id" method="GET">
<service class="PulsestormApitest2ApiThingRepositoryInterface" method="get"/>
<resources>
<resource ref="anonymous"/>
</resources>
</route>
Magento is going to look at PulsestormApitest2ApiThingRepositoryInterface for the type implementations and not the concrete class you have configuration via di.xml. In other words, if you put your @param int $id in the concrete get methods instead of the interface, Magento wont’ be able to find it will will throw a confusing “No such Class” exception when you try to call your API method.
The key to that exception message is the extra space. Magento goes looking for a type hint, assuming its a class by default (vs. a simple/scalar type like int or string)