Better API documentations

image

It is a tedious job to write api documentations, and we have been using word documents and excel spreadsheets to create api documents.
But they are difficult to follow and search though, what if there was an easier and cleaner way to create API documents? When I started working on my latest project I was searching for an efficient way to write API documents and a way to generate beautiful documentations, my quest for finding the best api documentation tool lead me to API Blueprint.

What is API Blueprint?

API blueprint is a language based on Markdown which allows you to write API documents clearly, moreover it has great tools which takes in your api blueprint document and convert it into beautiful html API documentation and much more.

Useful tools:

Here are some tools which I find useful, that you can use with your api documentation written using API Blueprint. These tools make the API blueprint documents very powerful. There are tools generate beautify html documentations to even create mock api servers.

Creating Online documentation:

There is a web app called as Apiary, which allows you to write in api blueprint format, and it generate beautiful online documentations, it also provide mock api server which will emulate your API based on the documentation, which is pretty useful if you don’t have the API server ready yet and want to use the APIs for prototype the applications.
It will allow you to quickly build and test the API, without writing a single line of code.

API blueprint document into html documentation

There is an awesome tool called as Aligo which will allows to create beautiful html documentation from the api blueprint document.

API blueprint document into POSTMAN collection

A utility called as Blueman allows you to convert the api blueprint domination into POSTMAN collection, which you can import into your POSTMAN REST Client.

Local Mock Server

API Blueprint Mock Server create a local api mock server using the api blueprint which you have provided, which you can use to prototype REST APIs.

Mastering web-storm

I am big fan of sublime text, and I use it extensively. Then I came across WebStorm, I like it and I want to learn more about it, because any craftsman should know how to use his tools effectively.
So I was looking for some tutorial and videos on mastering web storm and I came across this excellent video by John Lindquist. I highly recommend that you watch the video.

I have also tried to summarise what’s there in the video, but I recommend that you watch the whole thing, but for those who cannot spare the time to watch the whole thing, here is the excerpt:

Code Inspect:

Webstorm offers a nice code inspector, and to inspect code, right click on any directory inside Webstorm and click inspect Code.
It will give you a list of the issues and warnings and improvements which you can make, and is kind of really useful when your are doing code reviews and stuff like that.

Autocomplete Shortcut: Whenever a small bulb appears in Web storm, it indicated that Webstorm has some suggestions, and you can hit alt+Enter to bring the menu which shows the suggestions.

Go back in time: Webstorm has a nice auto-save feature, you don’t have to manually save things in Webstorm, and when you have changed something and want to revert your change you can go back in time by: Right-click-> local history

Getting things from CDN: When using CDN in script tags and stylesheets src, Webstorm will show a warning, you can hit alt+Enter->Download locally, by doing that it will download the linked file and show autocomplete off that.

Fine tune suggestions: In Webstorm you can fine tune the settings about auto-complete, suggestions, warning and errors.
Click on the lower right hand side corner->on hector the inspector and fine tune the inspection

Keyboard shortcuts:

To learn about keyboard shortcuts, go to
Shorcut Foo

Actions:

Cmd + Shift + A bring the action bar.
Select content, and press cmd+shit+a and select create live template.
And add variable by $name$ and $end$ to specify where the cursor ends.
Webstorm uses velocity template language.

Refactoring

Refactor this shortcut CMD+SHIFT+ALT+T
/+tab automatically generate the document
**Cmd+Alt+V
to pulling out variable.

Open up the file structure: can also be invoked by cmd+f12

To navigate project: cmd+shift+n, wildcard are also supported
s/a/*.js -> source/auto/ and all the javascript
cmd+alt+shift -> type the name of the method
and cmd+shift+i while doing this, will also show preview of the file, and cmd+shift+j while doing that will show documentation if available.

Version control:

Webstrom also has an integrated VCS manager, to bring the VCS Popup hit Ctrl+V.
Webstorm is also integrated with Github, you can easily import your github repos in Web-storm.

External tools:

To add external tools, go to Preference -> External tools and add details about the external tools you want to add, for e.g. Yeoman

File launchers:

If you create a coffee script file, it will ask you to add a watcher, and it will generate the corresponding js file, same if for sass etc.

Dead Simple Screen sharing (DSS) – Overview

Grab source on GitHub

Project site

Sometime ago a developed an open-source screen sharing application called as DeadSimpleScreenSharing which allows you to share your screen with anyone right from your browser.
It requires you to install an extension, when you click “Share your Screen” button on that extension, it will gives you a unique url which you can share with any number of people, and they can view your screen.
In this blog post I will give a brief overview on how this application works.

The Extension:

The DSS requires you to install an extension, a extension is required because there has to be some application running background which listens to tab changes and transmits this data to the server.
The extension uses the chrome extension api’s caputreVisibleTab() method get the visible tab and attaches mutationObservers and listen for DOM changes, when there is a change in the DOM, it transmits the data to the server via web sockets.

The Server:

The server is written in Javascript(node.js) and uses web sockets (socket.io), each session is namespace by unique id which is generate when the user presses the “Share your screen” button on the extension.
The server just receives the data and forwards it to all the connected clients in that namespace.

Get it working locally:

If you want to run DSS locally, you need to have:
1. Node.js installed
2. Install express using ‘npm install express’
3. Install socket.io run ‘npm install socket.io’
and follow along the video.

Share your entire screen using Chromecast

Google’s chrome cast allows you to bream content from your computer/phone to TV, and you can play youtube videos, music, etc. It allows also a really nice feature called as tab sharing, it allows you to share your Google chrome tab to the TV.
But it doesn’t allows you to share your whole screen, in the post I’ll explain how you can do that.

Things required

  1. Latest version of Google Chrome
  2. Chromecast
  3. Google Cast extension installed in google chrome

Procedure

  1. Visit https://html5-demos.appspot.com/static/getusermedia/screenshare.html
  2. Click on “Capture your screen button”
  3. Click on Chromecast extension and share the current tab
  4. Minimise Google chrome and enjoy.

Now can see your screen, but you can also a white border which is not nice, and you can’t get a full screen, to get past that you need to do a bit of extra work.

Download the zip package and extract it’s contents, and install Node.JS if you don’t have already.
Then open terminal in mac or Command Prompt in windows and type “cd “ and drag and drop the “server” folder into the terminal window.

Then run “sudo node app.js” and visit https://localhost (Note:It’s https not http), Google Chrome will give you a warning, and you can safely ignore it, because the certificates which I have created for https to work are not verified by any recognised issuing authority.

You’ll now see your screen, now share this tab with chrome cast and minimise the Google chrome.
Enjoy!

If you have any questions, ask them in comments below.

An app every programmer must use

As a programmer I want be constantly updated with technologies/programming languages I use, I want to read tutorials, tips, best practices and wanted to know about new tools and frameworks that are coming, and for that I was constantly asking people about best blogs / websites about Technology-X, and I was also very often bombarded with the questions like: What are the best Python blogs? or What are the best ruby on rails blogs? and What’s the best IDE for java development? etc.

But there is no solution available to get all this information in one place, so I thought of developing one: I call it Ken.

It is an Android app which keeps you updated with the latest programming news, you have to select your interests e.g: Node, Python, Javascript, Android etc. and it will show you all the latest news related to these technologies.

Ken is tool which I needed badly and I think a lot of other people can benefit from it, so if you are having the same problem which I had: Try Ken

Download from Google Play