Remote methods mapping in JSON

[nikita-leonov]

Would be nice to have an option to define remote methods mapping to an actual classes in JSON. So we will have complete REST interface defined in one place with a logic and complex cases in JS. I do not see why some of such constructions could not be a part of JSON mapping:
ApplicationModel.authenticate,
{
accepts: [
{arg: 'appId', type: 'string', required: true},
{arg: 'key', type: 'string', required: true}
],
returns: {arg: 'accessToken', type: 'object', root: true},
http: {verb: 'post'}
}

[raymondfeng]

Your proposal is aligned with the direction to make it possible to describe the remote methods using json. One idea is to have a routes.json to map http reqs (verb, url, content-type/accept) to nodejs methods.

[nikita-leonov]

👍 thanks. Wold be helpful feature. As well as UI for simplifying this configs definition as a step after all configuration options will be available in json. I can clearly see how this solution will overcome parse.com and other MBAAS with such roadmap.

[ritch]

@nikita-leonov (and anyone else reading)... proposals / drafts for a routes.js spec are very much welcomed. We are happy to take contributions 😄

[nikita-leonov]

I would recommend to piggyback on existing solution instead of inventing some new standard. This is healthy for product, third-party community support and moving complete industry forward.

I know four solutions that could be somehow used for definition of resources mapping and :

• WSDL (http://www.w3.org/TR/wsdl) — well known. Too complex :)
• Mashery iodocs (https://github.com/mashery/iodocs) — main purpose is the same as for swagger, however I believe it could be used as a base as they represent all complexity of APIs within their standard.
• RAML (http://raml.org) — RESTful API Modeling Language. This one is cool but so far lack of traction. Could be a nice idea to review.
• WRML (https://github.com/wrml/wrml/) — Web Resource Modeling Language. Developed by Mark Masse, author of book "REST API Design Rulebook. Designing Consistent RESTful Web Service Interfaces". Nice book, nice thoughts. He had a plan to develop language for describing APIs, but it progressing not very fast. Possible we may try to reach him and cooperate. I requested specification for a standard, just for an option to compare with other solutions that we I listed. So far it is weakest option from a list ;(

I really like RAML. It is modular, extendable and so on. Current approach with json is really limiting as we forced to define everything within one json file. On a big APIs current approach will become a mess. Also Masher iodocs could be a nice option from a business development standpoint for strongloop and loopback. IODocs is weaker form a technology point of view as it is not a standard, it is a tool like swagger but with own specification of mappings for methods and resources. But at least they have all use cases covered. Btw currently swagger do not shop remote methods, so could be an option to solve multiple tasks at once — get specification for a mapping, get right tool for self-documented APIs and build relationship with Mashery.

[nikita-leonov]

One more item in favor of RAML they have JavaScript based parser implemented — https://github.com/raml-org/raml-js-parser It capable for running in node.js.

[raymondfeng]

Thanks for the ideas. We have been exploring most of them. Swagger is currently used for the API explorer.

There are probably a few layers in play:

1. Define the data models (LDL)
2. Define the method signature (as JS is weakly-typed lang)
3. Define the mapping between a remoting transport/protocol and the Node.js method

Ideally, we should be able to declare/derive the metadata declaratively or programatically. Item 2 is more tied to the JS method, some sort of annotations should work. Item 3 could be further decoupled.

[nikita-leonov]

Agree regarding data models. Not all the standards cover this. For example RAML is more API oriented rather than resources / models oriented specification. That is why I provided WRML as a reference as there work ongoing on defining APIs by using resources terms which is more in line with your current approach.

I will think a little bit more about this task in direction of leveraging existing technologies and standards. It is much harder to invent and develop something new, rather than leverage existing functionality. I strongly believe that there is technology available that will fit the goal.

[ritch]

@altsang @raymondfeng @bajtos and I discussed this a bit.

Points in our discussion:

• LDL is for defining anything in loopback
• We can output to these other formats (RAML, Swagger, etc) but LDL is the native input/output format for LoopBack.
• We should support exporting other REST-DSL-ish formats like we currently do for Swagger in the explorer
• We should also continue to provide hook APIs (you implemente a JS function) where a feature is impractical to implement in LDL.