Re: Some suggestions for the SOAP api

Hi Chris, hi all! :)

> 2.)  The <m:warning> elements don't include any <m:explanation> (even though
> the web API uses this).  This should be added

It is already there, Chris, maybe it's just the tests you've made,
but I've personally found some explanations for warnings, exactly like
errors. Here's for example some of the output for validating cnn.com
home page:

<m:warning>
    <m:line>1916</m:line>
    <m:col>39</m:col>
    <m:message>
      NET-enabling start-tag requires SHORTTAG YES
    </m:message>
       <m:messageid>247</m:messageid>
       <m:explanation>
         <![CDATA[
            <p class="helpwanted">....</p>
            <div class="ve mid-247">....</div>
          ]]>
       </m:explanation>
      <m:source>....</m:source>
</m:warning>

> 3.)  The web API includes a summary message for all warnings: "The following
> missing or conflicting information caused the validator...

I totally agree! If this message is unique, it hasn't to be included
in the soap api for it will be a kind of redundancy, else it should be.

> 4.)  The web API includes 'info' elements.  So far, I have noticed them
> woven in with the errors but I "think" I might have seen one once in the
> warnings section.  I am not including these in my example because I don't
> know if they are their own category or just a "type" of error and warning
> (Oliver -- I could use some help here).  Anyway, if they're useful to web
> API users, I want 'em too.

I've noticed this thing too! That blue icon!
If this information is in the website version, it should be also
in the soap output. I want 'em too, monsieur Olivier! :)

> + <m:feedbacktext>Suggest improvements on this error message through
> our feedback channels</m:feedbacktext>

Chris, I totally agree with the rest of the recommendation, but I hesitate
on this one.
Because if this text will remain the same for every link, that would be
really a waste of bandwidth ;-)  unless this message is a direct function
of the error/warning and thus is not the same for all the errors/warnings
feedback invitations links.

And I think that it's up to the api consumer to determine his message
for inviting people to give feedback.
So, if it's allways the same, I'd rather write my own message, something
like: "guys give us feedback, and you gals some of thee tender hugs too!" ;-)


Karim
--
http://akoncept.com
Innovate Humanum Est

Received on Tuesday, 16 October 2007 02:26:48 UTC