Overview


Introduction

What is Webshell?

We are happy to present you webshell.io – an API of APIs trough a Javascript, declarative, evented, data-retrieval and aggregation gateway for HTTP APIs, built on node.js. Through Webshell, we want to help developers to develop application faster using APIs.

Webshell.io reduce the number of lines of code required to call multiple HTTP APIs mixed with some client side APIs. Simultaneously bringing down network latency and bandwidth usage, for mobile for example.

Webshell consists of a top layer of node.js focused on APIs, transforming API endpoints into Javascript objects, inspired by UNIX shell scripting paradigm, and this node.js-based runtime will process webshell scripts written in Javascript or Coffeescript throw an HTTP request.

Why using Webshell?

HTTP based APIs are now an integral part of the web, they even compose a coherent part of it we often call the programmable web. More than 8500 open APIs and their providers companies use the Web for content and information delivery through these APIs. In this growing part of the web, there are still several pain points for application developers attempting to integrate and script APIs for their applications.

Most real-world client apps need to mashup multiple APIs in one go. APIs mashups are often complicated as client apps need to worry about :

  • - authentication protocol which often are not the same specs
  • - endpoint description which oblige you to check the API documentation in depth to see each time at same functionalities between 2 APIs have not same method name
  • - data format which oblige you to parse XML or JSON response from an API to fit with the reception API when you make an API workflow
  • - order of requests, inter-dependencies, error handling, and parallelization to reduce overall latency.
  • - HTML views that you have always to do again and again.

With 100 new APIs per week and 1 000 000 expected for 2017 this will grow exponentially.

We found that these issues have three critical impacts: development time, end-user experience and engineering clock speed

The goal of webshell.io is to ease these pain points:

  • - By transforming all API endpoints into javascript objects, it become easy for developers to integrate, combine and script any APIs together, and automatically assemble the data you want on the client-side code.
  • - By using a Javascript interface to declare and use API calls, their interdependencies, you can cut down the number of lines of code from hundreds of lines to a few, and the development time from entire sprints to mere hours. Using Javascript, you can create new consumer-centric interfaces that are optimized for your application’s requirements.
  • - You can use webshell.io as an HTTP gateway between client applications and API servers side or client side so that webshell.io can process and condense the data to just the fields that the client needs and also providing the views that you don’t have to make again and again. This helps reduce the number of requests that the client needs to make as well as the amount of data transported to clients.

Getting started

All you need to get started is a Webshell Account, a supported browser, and a basic understanding of JavaScript. If you're new to JavaScript, MDN's JavaScript wiki has a lot of information.

Create an app in your Dashboard which will generate a valid API Key.

Hello World!

The following example is the simplest app you can do with Webshell using the Javascript SDK:

<!DOCTYPE HTML>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title>Hello World!</title>
  <script type="text/javascript" src="http://code.jquery.com/jquery-1.8.2.min.js"></script>
  <script type="text/javascript" src="http://api.webshell.io/sdk/js?key={API_KEY}"></script>
  <script type="text/javascript">
$('document').ready(function() {
  wsh.exec({
    code: function() {
      echo('Hello World!');
    },
    process: function(json, meta) {
      $('body').append(meta.view);
    }
  })
})
  </script>
</head>
<body>
</body>
</html>

You can find more information about the JS SDK here

Javascript as a Service

Webshell is an original API which take as HTTP parameter Javascript code. We execute the code on our server and give you a consistent response in JSON or XML. To execute code, just call this url:

http://api.webshell.io?code={code}&args={args}&output={output}&key={key}

It enables developers to script APIs together and combine them easily either HTTP APIs (like facebook, Twitter, Spotify...) or client side APIs (like Google Maps, Google Chart, Youtube Player...). To do that, we made the Webshell's Standart library, some simple function to allow you make HTTP request, access your account's file system and lots more.

$> curl --url "http://api.webshell.io" -d 'code=get({"url":"https://api.metwit.com/v2/weather","params":{"location_lat": "45.45", "location_lng": "9.18"}})'
[
  {
    "objects": [
      {
        "weather": {
          "status": "clear",
          "measured": {
            "wind_speed": 3.084,
            "wind_direction": 140,
            "temperature": 288,
            "humidity": 51
          }
        },
        (...)
      },
      (...)
    ],
  },
  {
    "_meta": {
      "cookie_add": {
        "sid": "CfLFMRVAZ9ljhH9U571Lp25E"
      }
    }
  }
]

The code given in parameter can be complex and coding in this way is not simple so we made some SDKs - currently available in Javascript (using jQuery), and node.js but we're working on SDK for PHP, Ruby, Python and more.

//Same exemple using SDK - node.js or jQuery (same syntax)
wsh.exec({
  code: function() {
    get({
      url: 'https://api.metwit.com/v2/weather',
      params: {
        "location_lat": "45.45",
        "location_lng": "9.18"
      }
    })
  },
  success: function(data) {
    console.log(data);
    //todo
  }
})
  

Learn more about Webshell API and SDKs

File system

We let you some space to store data and scripts on our platform. It let you write modular code to be reused in every project.

To let you manipulate your files in a simple way, we have implemented some builtins function in the standart library of Webshell:

/*
** I can write in my user directory some data (here in a file named `test`)
** replace login by your login ;)
*/
write({path: fs.login.test, data: "Hello World"});

/*
** read and display the test file
*/
cat(fs.login.test);

/*
** Execute helloWorld file of a user
*/
fs.login.helloWorld();

/*
** You can chain directories
*/
fs.login.directory1.subDirectory2.file

Currently, everybody can read and execute files of everybody but you can write only in your user workspace. We're working on setting rights (private file, team member), it will coming soon ;). In most case, it's not a problem thanks the APIKey manager, You can make scripts using lots of private key stored in the APIKey manager that stay private and don't display them in your source.

You can use this file system to share data or scripts with the community.

Cloud9 IDE

To manage your file, we have integrated Cloud9 IDE adapted to the Webshell file API. You can edit and run your scripts in your browser.

You can prototype fastly some mashups or design a complex wrapper for your API in this IDE. Lots of features is available in C9 : Visit Cloud9

APIs endpoints as Javascript objects

The idea behind Webshell is that it is easier for developers to use and script APIs with the whole expressivity of a programming language for APIs than to make the traditionnal way using REST/JSON protocols.
Webshell has transformed every APIs endpoints into Javascript Objects, via its builtins and file system.

As we saw in File System chapter, you can store scripts into files on your File System and execute it in your application and/or in your others scripts. So, we made a base of scripts based on most popular APIs and put them in the user bin (we chose bin username for /bin on Unix system).

fs.bin.spotify.searchAlbum('plastic beach');

To simplify the use of APIs, we setted a global variable apis to fs.bin. So you can write the same code in this way:

apis.spotify.searchAlbum('plastic beach');

All APIs on the platform are documented in the API Explorer and you can checkout our bin user on github - webshell/APIs.

It becomes easy to play with APIs into your apps:

var m = apis.google.maps({height: "215px"})
m.center("San francisco")
m.zoom(9)

m.addMarker({
  address: "Cityhall, San Francisco, CA",
  icon: apis.gravatar("team@webshell.io", {view: null})
});

m.directions({
  origin: "Cityhall, San Francisco, CA",
  destination: "Liberty Island, New York"
});

APIs Authentication made easy

To be authenticated should take a maximum of 5 minutes but in the reality, it tooks lots more time. You need to find a good OAuth library which support the API you want to use and setup your backend to receive the callback and so on... On Webshell, you have just to setup your API Key in the API Key manager - Dashboard

apis.facebook.auth().success(function() {
  //this is executed when the user is authenticated to facebook
  return apis.facebook.me(); //return user information
});

We manage query auth, http basic auth, oauth 1 & 2 and more...

When you create an app on facebook, we associate a callback for OAuth2 and OAuth1 callbacks.

Add your API

This is an overview on how add API on Webshell. All is described in detail in Add your API

As all APIs on Webshell are written in Javascript using the Webshell standart library, you can write your own scripts and publish them as a new API on the platform.

You have 4 ways to add APIs on Webshell:

  • - in Javascript
  • - from a WADL File
  • - from a SWAGGER File
  • - from a Mashape XML file

If you have a WADL, Swagger or Mashape XML file, it will be easy to integrate it into Webshell. We made some builtins function in the Webshell standart library that enable to generate Javascript files and documentation in HTML from these API description files. For little API with few endpoints, you can easily do a wrapper yourself. Example for metwit we saw in Javascript as a service chapter

You would like to call it like fs.yourNickname.weather({lat: "45.45", lng: "9.18"}); (replace your nickname by your nickname on webshell). You could just make something like that in your file system

login/
  weather/
    weather

In the weather file, write the following:

//fs.yourNickname.weather.weather
if (!args.lat || !args.lng)
  throw new Error('You have to specify `lat` and `lng` argument');
get({
  "url":"https://api.metwit.com/v2/weather",
  "params":{
    "location_lat": lat,
    "location_lng": lng
  }
});

It's a great way to make simple script with one functionnality.

Now you want to make the integrate the complete metwit API, you could use the following structure:

login/
  metwit/
    metwit

With the following code in metwit file using exports (or module.exports)

exports.weather: function(args, opts) {
  if (!args.lat || !args.lng)
    throw new Error('You have to specify `lat` and `lng` argument');
  return get({
    "url":"https://api.metwit.com/v2/weather",
    "params":{
      "location_lat": lat,
      "location_lng": lng
    }
  });
}

exports.anotherMethod: function(args, opts) {
  echo('Todo :)');
}

Then you can call your script like that: fs.login.metwit.weather({lat: "45.45", lng: "9.18"}); or fs.login.metwit.anotherMethod();

Once your script stabilized, you can publish it on the API Explorer.

You can configure the authentication of your API using a conf.json file in your metwit folder (cf Add your API / conf.json).