Is there a lightweight method to describe web services, similar to robots.txt or sitemap.xml?

Question

I'd like to provide a very lightweight method to describe my web services. No WSDL, WADL or similar complex stuff. Just a mapping from the web service's base URL to a simple description which can be detected and parsed automatically. Basically

• The name of the service
• A link to some human readable documentation (optional)
• Possibly a contact address
• Usage conditions, URL patterns etc. are less needed to keep it simple.

The best I could find is OpenSearch Description Documents, but first it could be simpler with plain text config files, and second there is no standard how to connect these service description documents to arbitrary web services (only autodiscovery in ATOM/RSS and HTML).

I thought about creating my own format and provide it similar to robots.txt:

$ curl http://example.org/services.txt

service: http://example.org/foobar
name: Foobar API
about: http://example.org/foobar-doc.html

service: http://example.org/some/unapi
name: Example ORG's unAPI

# additional fields, to be discussed
standard: http://unapi.info
pattern: ?id={id}&format={format}

So if you know the base URL of a service, such as http://example.org/some/unapi, you can look up at least the name in the service description file.

Instead of defining my own standard, however, I'd like to know whether there is already something similar to reuse.

Answer 1

There is a standard, but its called WSDL.

While the WS* standard are dauntingly complex and all encompassing in the breadth of their coverage in practice its pretty easy.

There is a very comprehensive and mature set of tooling and implementation built up around SOAP. In most cases all you need to write is the WSDL itself and the actual business logic service in Java, php, python C++ or whatever. The tooling and SOAP engine does the rest -- including responding to requests for a description of the web service.

There really is not much point in defining your own standard in isolation as its unlikely anyone but yourself would use it.

Although its not yet a standard the JSON SMD proposal may be more to your liking. Its much simpler than WSDL although it still very much describes the interface itself rather than the higher level description (contact details, ownership etc ) you desire.