Best practices for representing Metadata

[igtsvi]

Hello,

I am working on a set of REST APIs for which I need to define a parallel set of APIs that describe the shape of the objects returned in each end-point (its metadata).

For example:

GET /api/lifecycles/{id} - returns a particular lifecycle 

GET /api/metadata/lifecycles - returns the metadata describing each property of lifecycle

The lifecycles object is complex and contains a nested JSON structure with arrays and links to object relationships. Is there a best practice around defining metadata which describes the structure of objects? I've read through json-schema spec, which seems promising, but I am not looking for creating a structure validation, just a description of the object.

Thank you,

igtsvi

[danieleli]

U can take a look at swagger from wordnik. It's a spec for describing Apis that hooks into a decent frontend (swaggerui). There are several libraries for different backend languages. I've been working on swagger.net lately.