Generic Web API Client for NodeRed

[Carlos Pedrinaci]

Hi,

I've been working on a node that could allow people to easily invoke Web APIs without the need for crafting one node per specific API.

My first go at this can be found at: https://github.com/kmi/swagger-nodered

Essentially the client relies on the existence on some declarative description about the API (endpoints, parameters, etc). For this we make use of a specification called swagger which does a good job at it. Swagger also has quite some tooling around it. In fact, the node I've developed relies on an open source swagger client for node.js.

If you want to test it find below a flow description with some example invocations. It actually includes invocation to both the typical swagger example but also a publicly available API out there.

There are still quite a few things to polish and extend but I hope that this would already allow you to see the potential of having such a node within NodeRed. 

Any comments/suggestions/fixes are most welcome!

Cheers,

Carlos

[{"id":"e5ccd16a.1a333","type":"debug","name":"","active":true,"console":false,"complete":false,"x":731,"y":175,"z":"f4c3b273.0b3c5","wires":[]},{"id":"6b4ae34f.94b51c","type":"api-client","api":"http://petstore.swagger.wordnik.com/api/api-docs","resource":"pet","method":"getPetById","intype":"","outtype":"","name":"","x":420,"y":114,"z":"f4c3b273.0b3c5","wires":[["e5ccd16a.1a333"]]},{"id":"49c7b875.b63848","type":"inject","name":"","topic":"","payload":"{\"petId\":\"1\"}","payloadType":"string","repeat":"","crontab":"","once":false,"x":134,"y":118,"z":"f4c3b273.0b3c5","wires":[["6b4ae34f.94b51c"]]},{"id":"38d9d213.c7262e","type":"inject","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"x":135,"y":191,"z":"f4c3b273.0b3c5","wires":[["cac748f5.3538b8"]]},{"id":"cac748f5.3538b8","type":"api-client","api":"http://www.zaragoza.es/api/kos","resource":"junta-administrativa","method":"listar","intype":"","outtype":"","name":"","x":425,"y":187,"z":"f4c3b273.0b3c5","wires":[["e5ccd16a.1a333"]]},{"id":"164032fe.e9bfcd","type":"api-client","api":"http://www.zaragoza.es/api/kos","resource":"junta-administrativa","method":"detalle","intype":"","outtype":"","name":"","x":431,"y":261,"z":"f4c3b273.0b3c5","wires":[["e5ccd16a.1a333"]]},{"id":"66caf356.99350c","type":"inject","name":"","topic":"","payload":"{\"id\":\"3\"}","payloadType":"string","repeat":"","crontab":"","once":false,"x":115,"y":261,"z":"f4c3b273.0b3c5","wires":[["164032fe.e9bfcd"]]}]

[Dave C-J]

Looks interesting ! 

Couple of things when I gave it a poke....

--
http://nodered.org
---
You received this message because you are subscribed to the Google Groups "Node-RED" group.
To unsubscribe from this group and stop receiving emails from it, send an email to node-red+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
regards

Dave Conway-Jones

[Dave C-J]

Hi Carlos,

Very interesting... couple of things when I gave it a poke

    1) why not just call the node swagger ? as it's all about the swagger api... 

    2) we now support npm install so if you add a package.json, license (you already have the Readme) - then publish it to the npm site - we can just install it very easily...  PS - ideally we would like it called something like   node-red-contrib-swagger  - but it's your node :-)   - for an example of the extra files you need see https://github.com/node-red/node-red-nodes/tree/master/hardware/blinkstick  

   3) The initial node appears - but if I try to edit it I get an error - api-client : ReferenceError: window is not defined - and so nothing works from that point onwards.... :-(

--
regards

Dave Conway-Jones

[Nicholas O'Leary]

Just to add to Dave's comments about npm packages - the documentation for that is here: nodered.org/docs/creating-nodes/packaging.html

[Dave C-J]

Carlos,

and apologies - once I fully read the install to add the necessary js files to the public/swagger dir it all works great....

so yes ---- that needs thinking about some more to...

[Dave C-J]

Carlos,

and apologies - once I fully read the install to add the necessary js files to the public/swagger dir the Gui works great 

so yes ---- that needs thinking about some more to...

But the error message re window is not defined still remains 

--
regards

Dave Conway-Jones

[Carlos Pedrinaci]

Hi,

Thanks.

I thought indeed about calling it swagger but I had a couple of concerns:

- Swagger is not meaningful unless you know what swagger is. Api Client seemed more meaningful in this regard ... 

- A minor issue is also that I’m not sure whether the people behind swagger might have issues with that naming since it has not been developed by themselves.

That being said I am actually also rather unclear as to which name would be best so if the preference is to call it swagger, I’ll just change the name.

Is ' node-red-contrib-swagger’ the preferred name?

Regarding the packaging I had read a bit about it but I wasn’t sure this is already in place and considered the best practice. Indeed an npm way of installing things is much better. I’ll take care of that asap.

Cheers,

Carlos

-- 
Dr. Carlos Pedrinaci 
Knowledge Media Institute - The Open University 
Walton Hall, Milton Keynes, MK7 6AA 
United Kingdom 

Tel: +44 1908 654773 
Fax: +44 1908 653169

[Nicholas O'Leary]

The main issue you'll face today is there is no way to 'install' the extra files you require into the public directory. We haven't had a need to do that with any other nodes, so don't have a mechanism in place to support it.

The alternative is for your node to add its own http end points to the node-red express app to provide the required files.

Nick

[Carlos Pedrinaci]

Hi

On 16 Jul 2014, at 14:26, Dave C-J <dce...@gmail.com> wrote:

Carlos,

and apologies - once I fully read the install to add the necessary js files to the public/swagger dir the Gui works great 

so yes ---- that needs thinking about some more to…

Yes, the node uses some client-side javascript to provide a dynamic form. Basically the swagger description is loaded and interpreted also on the client-side to show the existing resources, documentation, etc.

Unfortunately for this to work you need to have those javascript files publicly available. The way I managed to do this was by adding them to the ‘public’ folder but I believe there should be a better way to do this, or at least, an agreed upon manner. I suppose no other node required specific client-side javascript?

Let me know how I should go about this.

But the error message re window is not defined still remains 

Could you perhaps give me some more details about the error you are getting?

I have tested it on Safari, Chrome and Firefox running on NodeRed 0.8.1.git 

Cheers,

Carlos

[Dave C-J]

Hi Carlos

well to me api-client is so general it could mean anything - the whole of the iot is built on APIs :-) - so I'd certainly prefer it to be specific to the type of api it is, which is swagger in this instance - the Info / hover help should  explain that if someone want to know more. (though just looking now the hover on palette node help (first line of help section) doesn't seem to be populated. - AHA!  remove the commented lines from that help section ;-)

The node-red-contrib-swagger name is for the npm only (in package.json).

--
regards

Dave Conway-Jones

[Carlos Pedrinaci]

On 16 Jul 2014, at 14:42, Nicholas O'Leary <nick....@gmail.com> wrote:

The main issue you'll face today is there is no way to 'install' the extra files you require into the public directory. We haven't had a need to do that with any other nodes, so don't have a mechanism in place to support it.

The alternative is for your node to add its own http end points to the node-red express app to provide the required files.

I see. I will give this a go. Certainly it would make things easier to handle. 

Which node is best to look at for an example? The http one?

Cheers,

Carlos

[Carlos Pedrinaci]

On 16 Jul 2014, at 14:45, Dave C-J <dce...@gmail.com> wrote:

Hi Carlos

well to me api-client is so general it could mean anything - the whole of the iot is built on APIs :-) - so I'd certainly prefer it to be specific to the type of api it is, which is swagger in this instance - the Info / hover help should  explain that if someone want to know more. (though just looking now the hover on palette node help (first line of help section) doesn't seem to be populated. - AHA!  remove the commented lines from that help section ;-)

Fair enough. I had in mind 'Web APIs' actually but I get your point and agree with what you suggest. 

Will fix both things soon (including the doc). Thanks for the suggestions.

Cheers,

Carlos

The node-red-contrib-swagger name is for the npm only (in package.json).

--
regards

Dave Conway-Jones

[Dave C-J]

Hi

not much more I can say. The Node-RED log says on start up - if a node has already been deployed.

16 Jul 15:41:18 - [red] api-client : ReferenceError: window is not defined

16 Jul 15:41:18 - [red] unknown type: api-client

Does swagger have to attach things to the global window object ? hmm I guess so...

One other thing Nick pointed out is that all the functions in the html are not in a closure so are all exposed globally

[Carlos Pedrinaci]

Hi,

I have addressed all the comments raised and hopefully fixed the issue you faced with “window is not defined”.

It has also been published as a package now:

https://www.npmjs.org/package/node-red-contrib-swagger

Cheers,

Carlos

[Dave C-J]

Carlos

This is really good ! - Definitely my "node of the week" - if we had such a thing...

[Dave C-J]

... or would be... if I could edit any of my function blocks... something in this node is stopping me edit any of my functions...  uninstalling it and all is good again...

--
regards

Dave Conway-Jones

[Dave C-J]

and palette category-wise I would call lit more of a function than an input... 

[Carlos Pedrinaci]

Weird. I’ll look into this. 

Carlos

-- 
Dr. Carlos Pedrinaci 
Knowledge Media Institute - The Open University 
Walton Hall, Milton Keynes, MK7 6AA 
United Kingdom 

Tel: +44 1908 654773 
Fax: +44 1908 653169

[Nicholas O'Leary]

Carlos,

the instructions don't mention anything about the dependency on shred.bundle.js and swagger.js.

as I mentioned before, we don't yet have a way for you to include additional .js files in the editor via an npm install - they would have to be copied in manually.

Nick

[Carlos Pedrinaci]

Hi Nick,

This should be now handled transparently by the node as you suggested. The node basically catches the ‘/swagger’ requests and maps it to the internal node_modules folder to get the right ‘js’ files needed. There should be no need for you to drop any files within ‘/public’ anymore. 

Seems to work on my side, does it not for you?

Cheers,

Carlos

-- 
Dr. Carlos Pedrinaci 
Knowledge Media Institute - The Open University 
Walton Hall, Milton Keynes, MK7 6AA 
United Kingdom 

Tel: +44 1908 654773 
Fax: +44 1908 653169

[Nicholas O'Leary]

Ooops - yes, I see it now. Ignore me :)

Nick