Re: Some suggestions for the SOAP api

Karim A. wrote:
> 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>
>   
Hmm, that's odd.  I haven't been testing live sites but, instead 
internal ones.  I don't have a mechanism built for getting SOAP output 
for a live site (I post fragments) so I copied the CNN page's source and 
handed it off to be validated as I normally do.  Two things struck me:

1.)  Yes those warning messages had explanations -- but the simple 
markup that I tested and posted earlier today also yields warnings that 
have explanations in the web version but not the SOAP.
2.)  All of the warnings on the CNN page were listed in the "Errors" 
section -- huh?
>> 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!" ;-)
>   
On the same page with you here Karim.  I would probably not use the W3's 
text either -- but that doesn't mean that other's would.  Now, if the 
message is truly ALWAYS the same, then I recommend that it be refactored 
into the general <m:errors> or, better still, a child of 
<m:markupvalidationresponse>.  That way, like the warning summary (which 
I also don't think ever changes), it's there in case you do want it and, 
if you do use it, changes w3 makes to its contents will propagate to 
your app automatically.


By the way, if you are concerned about bandwidth, you should push to get 
rid of all those extraneous tags and opt for attributes.  For instance, 
why not:

  <m:errors count="3">
    <m:error row="25" col="10" eid="321" feedbackurl="http...">
      <m:message>Blah blah blah</m:message>
      <m:source><![CDATA ...]></m:source>
      <m:explanation><![CDATA...]></m:explanation>
    </m:error>
     ...
  </m:errors>

Of course I know next to nothing about SOAP (I'm parsing all this stuff 
using ruby and some of its built-in XML tools) so perhaps all the 
structural hierarchy needs to be the way it is currently and what I'm 
suggesting here is bad practice.

-Chris

Received on Tuesday, 16 October 2007 04:44:37 UTC