Re: [DRAFT] Documentation API for W3C Markup Validators

On 12 Nov 2005, at 07:10, Karl Dubost wrote:
> [[[
> W3C Markup Validator is a Web service to encourage the validation  
> of your Web documents (List of supported document formats). It  
> exposes its Web service as a SOAP 1.2 interface, that you can use  
> in your own applications.
> ]]]

looks good.

> Flickr gives a list of clients (API kits) in different languages  
> (perl, java, python, etc.) implementing the access to the API.

This would be cool to have indeed. For perl, someone already "has"  
the module namespace that we would be using, but it interacts with  
the old xml interface, hence my trying to contact him. I don't think  
we would need to make many modules, but we should list the ones we  
know and invite developers of others to contact us to get listed.

> 2. Authentification for W3C Markup Validation service is NOT REQUIRED.

Is it necessary to say that auth is not required? A dev not seeing a  
requirement for auth and no "key" generation would guess, no? Plus we  
say it's public.

> I guess there's a missing example
>
> [[[
> - General case
> http://validator.w3.org/check?parameter1=value1&parameter2=value2
>
> _ Example for an EARL output of the W3C HomePage validation
> http://validator.w3.org/check?uri=http://www.w3.org/&output=earl
> ]]]

Do not use the earl output for the example, as we are yet to decide  
what we do with it.

> The Table is confusing for example for uri, upload_file, and  
> fragment. It seems it's another requirement: The minimum use of the  
> service is a call with one these three methods.

I thought mentioning it in the param description was sufficient. I am  
not sure it is such a great idea to complicate the document for these  
parameters, but if you want to give it a try, why not.


> So I guess if we want to make it more systematic, it will be  
> something like. Could we consider that the W3C Markup Validator is  
> a Web service with only one method (check)? and different parameters?

Yes.

> * Method name   (check)
>     - Description
>     - Arguments (uri, output, etc.)
>         - Description
>         - Possible Value
>         - Example Response
>         - Link to a real Example

Looks good, except for the example response. I think it's best to  
keep the response documentation separate from the request documentation.

But basically, your ideas seem sound and based on current practice,  
so please go ahead and commit if you have ideas of changes to the doc.

Thanks,
olivier
-- 
olivier Thereaux - W3C - http://www.w3.org/People/olivier/
W3C Open Source Software: http://www.w3.org/Status

Received on Monday, 14 November 2005 08:59:59 UTC