Hi omr, Thanks for the additional feedback.
My comments above refer to the old APIs and Custom Search element. The new APIs require a key from the APIs console. This is a hard, technical requirement - without a key, no requests will be filled. For the old APIs, I don't believe it says anywhere that you must use a key, it simply strongly recommends it. On the introduction pages, it goes so far as to say that "we do not require" keys for these APIs. The wording above the samples indicate that you cannot use INSERT-YOUR- KEY as your key. This is because a lot of people copy and paste the samples without changing their keys, so we're calling attention to it - if you try to make requests with this default key, *it won't work*. Therefore, the warning calls this out. Likewise, for the Custom Search element, we can't have people using the default key, so the warning is intended to get developers to change it. Since there is no harm in using a key, if existing users of the element read that and are enticed into getting one where they didn't have one before, no harm done. Yet, if someone misses the warning (perhaps because it's long enough to be glossed over), they may not understand why their code isn't working (because it uses the stock key). Of course, I could be wrong. I'll be watching the forum closely in the coming weeks and if there is a lot of confusion among users of the old APIs, we'll do what we can to clarify the documentation. Cheers, Adam On Nov 6, 1:15 pm, omr <[email protected]> wrote: > Adam, > > Thanks again for your reply. Here are some further thoughts. > > To recap: > Warnings such as this appear in the new CS API documentation: > > > "Warning: You need your own API key in order to use the Custom Search > > element." ... "Without a unique key, these [code] examples won't work." > > But as you wrote above: > > > "... keys ... are not required for the Custom Search element ...." > > You further explained: > > > "... As part of the documentation rewrite, we took a firmer stance ...." > > "... By using strong wording to increase key usage among new developers, > > the intent is to help make sure they don't run into problems later. ..." > > IMO, documentation should be clear and true. While there may be good > reason for 'strong wording' to a point, that warning is currently > worded such that it may appear at worst untrue (as your comments > appear to contradict it) or at best potentially confusing. > > As you say the aim is to "strongly encourage" key usage. I understand > that there are good reasons for that. But the warning as it now > stands could confuse not only newcomers, but also existing users of > Custom Search and Site Search (who vary widely in skill levels and > first-hand familiarity with the API). > > Presumably some who read the warnings might wonder if there's a need > to update their existing Search Element code to use a key, though in > fact that really isn't necessary for existing implementations (as you > have confirmed). > > I might suggest replacing the warnings with something like this > (I am borrowing some text from existing documentation and from your > reply): > > "... IMPORTANT: All developers creating new implementations using > this API are strongly advised to obtain and use an API key. Your API > key helps us to contact you if we detect problems with your > application. Developers using keys are also less likely to be > incorrectly identified as misusing the API. Your API key can help us > to help you avoid problems down the road. ..." > > Thanks for taking the time to read this feedback. > > -- omr -- You received this message because you are subscribed to the Google Groups "Google AJAX APIs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/google-ajax-search-api?hl=en.
