Re: [docbook-apps] REST API description

[David Cramer <david@thingbag.net>]

I don't think DocBook is the right vocabulary for modeling a REST API. 
There's an XML schema, WADL (Web Application Description Language) that 
is designed for that: 
https://en.wikipedia.org/wiki/Web_Application_Description_Language I 
would suggest putting the API specification in WADL and converting it to 
DocBook to combine it with your other content.

WADL includes features that let you reuse content, but all that reuse 
can make it difficult to parse. wadl-tools includes xslts that will 
flatten out the wadl. Do that first and converting it to DocBook will be 
much more straightforward:

https://github.com/rackerlabs/wadl-tools

You can see an example of that approach here:

https://github.com/rackerlabs/clouddocs-maven-plugin

If you need a proxy for your API, check out Repose: 
http://www.openrepose.org/ That wadl-tools stuff was developed in 
support of Repose. For more information, see this Balisage paper:

https://www.balisage.net/Proceedings/vol8/html/Williams01/BalisageVol8-Williams01.html

These days non-xml vocabularies for modeling REST apis are more popular. 
Each has its own strengths and weaknesses, depending on your needs.

https://swagger.io/

https://raml.org/

Regards,

David


On 12/5/17 2:23 PM, Jan Tosovsky wrote:
> Dear All,
>
> is there any recommended DocBook tag set for describing REST API?
>
> My current structure is depicted in http://drifted.in/other/docbook/rest.png
>
> I use common elements like sections, simplesects, tables, programlistings,
> tips, but not sure what vocabulary use for URL fragments (1) or parameter
> descriptions (3, 4).
>
> (1) uri
> (2) synopsis
> (3, 4) informaltable
>
> I especially don't like (3, 4) as tables are quite heavy/complex objects for
> kind of variablelist with headers, which could be even auto-generated using
> localized resources.
>
> Any thoughts?
>
> Thanks,
>
> Jan
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org