An Overview of REST Metadata Formats

Although the REST community initially took a stance against metadata for REST APIs, a number of metadata standards have none-the-less emerged over the last couple of years, mainly fueled by the need to document APIs for their consumers.

...

The common goal of current metadata formats for REST APIs is to specify

• Entry point(s)
• Resource paths
• Methods to access these resources (GET, POST, PUT, etc.…)
• Parameters that need to be supplied with these methods (Query, Template, HTTP Header, etc.)
• Formats of inbound / outbound messages/representations (JSON Schema, XML Schema, Relax NG, etc.)
• Status codes and error/fault messages
• Documentary information (descriptions, etc.) for all these

All these are somewhat derived from the principles underlying REST APIs – i.e. those of resources, representations etc. Non-functional aspects of APIs, like for example authentication (Basic, OAuth, SAML, etc.), security (encryption, signatures, etc.) and versioning are unfortunately still poorly addressed by most REST metadata standards. This is where the WS-* standards “shine”, but it is also what many refer to as WS-(death-star) – indicating the complexity of the WS standards that might ultimately lead to their demise. Hopefully the REST community will align around common standards and best practices more successfully than vendors did in the SOAP-domain around 10 years ago.

...

From: http://apiux.com/2013/04/09/rest-metadata-formats/