On Thu, Nov 06, 2003 at 04:33:05PM -0500, Clara Cabral wrote:
>
> I checked the archives for your documentation questions, submitted in June
> of this year. You're referring to
> http://www.opensrs.org/archives/dev-list/0306/0024.html, yes?
Yes.
> Your questions were acted upon, but it appears that no one actually informed
> you of the changes that resulted from your comments. Sorry for that.
Thanks. It's good to see that the changes have been made.
> [...snip...]
> > We were hoping to be able to use the new API change for check_transfer
> > that returns 'request_address' so we could inform our clients to make
> > sure they can receive mail at that address to acknowledge the transfer.
> > However, if we can only retrieve that information after a transfer has
> > been initiated, it is not as useful.
>
> This appears to me to be a change request, so I've submitted it as such. It
> will be evaluated according to our Product Change Request process, and if we
> do enhance the product to provide that functionality, the change will be
> broadcast in a future LRU.
Okay.
> Thank you for bringing up those issues. If you have an opportunity to,
> please review the resulting changes in the current OpenSRS API
> Specification, available from the Reseller Resource Center, and let me know
> if more clarification is needed.
I have just downloaded the latest version of the manual. There are
a couple of quibbles right away:
1) The new version is 2.1.9. The most recent version prior to this was
2.79. I see the note in the revisions section regarding the document
version system change, but really, couldn't you have started the new
versions with 2.80.1? Newer versions smaller than older versions is
just plain silly.
2) We use Linux systems. The latest available version of Adobe's Acrobat
Reader for Linux is 5.0.8. When I open the 2.1.9 PDF, I get the
following warning:
This file may contain newer information than this viewer can
support. It may not open or display correctly. Adobe recommends
that you updated to the latest version of our Acrobat products.
Please visit our product site at http://www.adobe.com/acrobat
Could you please ensure that future versions of the API Specification
PDF are generated with an appropriate compatibility setting?
Overall, my negative comments on the quality of the documentation relate
to request/response parameters that are either not documented, or when
they are documented do not match behaviour I see when communicating with
the OpenSRS servers.
In the past, I have refrained from attempting to point out all the
errors I have encountered simply because there are so many instances,
even per API command. I have asked for clarification only when I
couldn't determine what was going on by experimentation, or searching
the list archives for related discussions.
For example:
I get the following parameters back from the OpenSRS servers for a valid
lookup domain request:
{
'attributes' => {
'upg_to_subdomain' => undef,
'status' => 'taken',
'reason' => undef,
'email_available' => undef,
'price_status' => undef
},
'response_text' => 'Domain taken',
'is_success' => '1',
'response_code' => '211'
}
The documentation for Lookup Domain does not describe these parameters:
upg_to_subdomain
reason
email_available
The documentation does describe the parameter 'noservice' as being
'required', however, it was not included in the response. It is also not
included in the documentation's example response.
In addition, There is no Perl example of a 'domain taken' response, even
though there is an XML example.
In short: please make sure the documentation accurately describes
current client/server behaviour.
Thank you for your response. It is refreshing to see OpenSRS
participation on the list.
--
// 2 _____________________________________________________________
// / \
\\/ / | Paramnesia, n.: The inability to recall the correct meaning |
\\/ | of a word. |
\_________________________________ __________________________/
Ewan Edwards {e^2}, [EMAIL PROTECTED] |/
