Specification standard

[desmondmorris]

There should be a default specification for defining RESTful routes and models. Adapters would then be responsible for adhering to the standard.

Something that defined the following could be a good simple starting off point.

name
version
basePath
resource
 - routes
 - model

It may be worth looking at JSONSchema or YAML to use as a base potentially

[desmondmorris]

An initial effort towards this is here: 0b4566b3

[joshuajabbour]

While I agree we should have a common model somehow, the more I think about this the less I want to invent our own. I think we should pick one to use as our canonical one. It can be either one of the API definitions we currently support (Swagger, RAML, API Blueprint). Or maybe a lower level one, like JSON Schema / Hyper Schema. Both Swagger and RAML use JSON Schema for resources already...

One thing I do feel strongly about is being able to separate route specs from resource specs (and probably from a third "API meta spec"). By separation I mean both file-wise (no Swagger 2.0 "single, giant spec doc") and entity-wise (maybe I want to use Waterline models for my resources spec and RAML for the endpoints). Obviously, if the user wants one spec all the way, that should work too.

[desmondmorris]

@joshuajabbour +1 to not spinning our own. I think lower level is the desirable - JSONSchema is a good candidate. The only challenge is ensuring a default schema is defined per set of routes. This ensures we can properly scaffold the endpoints. Want to throw an example of what this could look like, together and separated.