search

apis-json / api-json

APIS.json an API discovery format
http://apisjson.org/
MIT License
111 stars 23 forks source link

Include API specification #6

Open nichtich opened 10 years ago

nichtich commented 10 years ago

The specification could be an RFC, W3C recommendation or any other kind of document. Two APIs with same specification can be accessed the same way (e.g. with the same client library). The human readable documentation of an API, however, is most likely unique per API because it includes branding and other information specific to the particular API instance.

kinlane commented 10 years ago

An RFC, W3C or even a media type is definitely on our roadmap as we consider the best way to solidify this in people's minds.

Our goal with the link references for each API will allow for referencing of any human or machine readable building blocks including branding, tos, docs, etc. etc.

kinlane commented 10 years ago

Thanks for your feedback!

njyx commented 10 years ago

I think for now as close as we can get is to point to the machine readable specifications in Swagger, Blueprint, RAML etc. unfortunately those are still tied to the instance of the API and not the "class". I'm not sure we can do much about this until a lot of generic API specifications are out there (e.g. in API Commons) and referencable.