A year ago I gave a talk at EVE Vegas about building RESTful CREST applications. My #1 recommendation was to specify representations in requests, but that’s hard to do when there is little documentation on which representations are available and what they contain.
Fortunately CREST is self describing: send an OPTIONS request to a CREST URI and a list of methods and representations that can be used with that URI is returned. The metadata isn’t in a standard format, so I built the crestschema library which can convert the CREST format in to more useful JSON schemas. The library works in browsers, in applications like crestexplorer, and from node in applications like crestschemaspider which can crawl the CREST API to find all reachable representations. Converted schemas can then be used with wide variety of software, libraries and languages to validate data from the live CREST API, generate parsers or automatically generate documentation.
With the schemas converted it’s easy to build crestmatic which uses crestschema and matic to generate the documentation. Adding a travis step to publish the generated documentation to gh-pages and wiring up nightli.es to trigger a build every night ensures that the documentation is automatically kept up to date. If you’d like to see some changes please feel free to submit a pull request or just donate some ISK to Capt Out if you find the documentation or code useful.