However, I'm not sure how the distinction between an API or OS is salient, because the API is exactly that: an interface. Regardless of valuable resources, the interface should do what it is documented to do, and I'm not sure that I believe it to "return the current RSSI".
I ought to first explain, 'automagical' is a word I use (specifically) to describe code and process which is taken for granted. For example, end users rarely think about all the things which need to happen automatically, before they see a web page in their browser, so it often appears to be somewhat 'magical' to them.
The distinction I was making, is that an O/S is a collection of processes (code which is executing), whereas an API is a collection of functions (code which could be executed).
If you were to dig into how Windows, OSX, iOS etc work with wifi, you would find that between the O/S and the network interface driver, there is a network discovery background service, which periodically polls the wifi hardware in order to maintain the various data structures associated with an access point. End user applications then call API functions to interrogate the structures maintained (automatically) by the O/S. In this way, the O/S provides applications with a layer of abstraction (encapsulation), so application developers don't have to worry about the hardware specific, Layer 2 (data link) stuff.
The costs of abstraction are always, runtime, RAM and power consumption. On a host like a PC or smart phone, which has Ghz of runtime, MB of RAM and potentially Amps of power to draw on, the cost of automating various network services is trivial. On an Arduino with it's Mhz, KB and milli-Amps, the cost of automating just network discovery would be relatively huge, leaving little resource left to do much else.
In the case of the WiFi shield, the distinction between API and O/S is not quite perfect, because the WiFi shield has it's own MCU which is running some code and providing some abstraction. However, the lack of resources can not be escaped and I think it is safe to presume the shield firmware, is mainly concerned with the bare essentials of Layer 2; managing radio transmission and the like.
Your example is much appreciated. I will play with the function I mentioned using this technique. Thanks again!
Happy to help.
I don't know whether this helps but as regards documentation and once again, this is just my view of the World. I always try to remember the English language is quite vague, compared to the programming languages it is used to document.