POD list of machine readable documentation specifications

OpenGovLD / specs

Linked Data vocabulary and API for parliamentary and committee information systems

17 stars 1 forks source link

POD list of machine readable documentation specifications #126

Open akuckartz opened 9 years ago

akuckartz commented 9 years ago

The POD site on https://project-open-data.cio.gov/v1.1/api/ contains this list of machine readable documentation specifications:

[x] Swagger
[ ] RAML
[x] API Blueprint
[x] HAL
[x] Hydra

Review those specifications.

akuckartz commented 9 years ago

On Swagger:

When it comes to truly RESTful Web APIs (aka hypermedia APIs) it is almost useless as it heavily relies on URL structures. In hypermedia APIs, however, the URLs are not known beforehand but conveyed at runtime.

http://www.quora.com/JSON/Is-Swagger-any-good

akuckartz commented 9 years ago

"API Blueprint" is about the automatic generation of human readable documentation but not machine readable API specifications..

akuckartz commented 9 years ago

The importance of this is reduced by the use of LDP (#131).