Vistas

TOOLBOX

LANGUAGES

API

De MorfeoWiki

Contenido

EzWeb API

EzWeb API is a minimalist approach for allowing gadgets to communicate with the "external world". This API is JavaScript and deals with two different high level communication flows:

Gadget to EzWeb-platform communication flow

Gadget access to services provided by the EzWeb platform (data storage, gadget communication, context data, user preference configuration) by means of "EzWeb Variables". There are 2 types of variables: Read-Only and Read-Write.

Read-only variables

Constructor (in JavaScript syntax): 

EzWebAPI.createRGadgetVariable = function(varName, callbackFunction);

API: 

#A gadget reads the value of the Read-only variable
EzWebAPI.RGadgetVariable.get = function();

From the perspective of a gadget, a Read-Only variable provides only 1 operation. A gadget can't set a value to a Read-Only variable. Only external entities (users or other gadgets through the wiring process) are allowed to assign a new value for a Read-Only variable.

However, a read-only variable must react when an external entity change it's value. These changes can't be predicted, so EzWeb provides an asynchronous communication style: when EzWeb platform detects a change in read-only variables, the platform invokes the callback function specified in the Read-Only variable constructor. Each read-only variable of a gadget, has its own callback function (aka handler), where it's defined how the gadget must react to changes on the associated variable.

Read-Write variables

Constructor (in JavaScript syntax): 

EzWebAPI.createRWGadgetVariable = function(varName);

From a gadget perspective, a Read-Write variable provides 2 operations:

API: 

#A gadget set a new value to the RW variable.
EzWebAPI.RWGadgetVariable.set = function(new_value);
 
#A gadget reads the value of the RW variable
EzWebAPI.RWGadgetVariable.get = function();

The get() method works on the same way in both variable types.

The set(value) method, send the new value of a variable to same EzWeb Services compatible with Read-Write variables (storage service and communication service between gadgets mainly). To show a detailed description about how to assign an EzWeb Service to a Read-Write variable, read about EzWeb Services

At developing time, gadget developers don't need to think about what concrete EzWeb services are necessary to each variable. The gadget coder only need to distinguish between Read-Only variables (external entities will provide value to the variable and this variable know how to react to the change) and Read-Write variables (the gadget will assign value to the variable invoking .set operation)

Gadget source code only deals with high level variables (read-Only and Read-Write), so it's very easy to change gadget behaviour only changing the service each variable is assigned to. The source code keeps unaltered and it's only necessary to change the template file. For a more detailed description of EzWeb low level variables, please read the Gadget Developer Guide [1]

Gadget to external-services communication flow

A gadget can access to any HTTP resource available on Internet/enterprise Intranets. EzWeb can only invoke natively pure HTTP requests (it can't directly exploit other communication technologies like SOAP-based Web Services, CORBA services, etc).

The AJAX-based EzWeb HTTP API is the following: 

EzWebAPI.send_get = function (url, context, successHandler, errorHandler, requestHeaders);
EzWebAPI.send_post = function (url, params, context, successHandler, errorHandler, requestHeaders);
EzWebAPI.send_put = function ( url, params, context, successHandler, errorHandler, requestHeaders);
EzWebAPI.send_delete = function (url, params, context, successHandler, errorHandler, requestHeaders);

If one EzWeb gadget need to invoke a service based on any different technology, an HTTP wrapper must be deployed in front of the original service. This approach is not intrusive: the original service doesn't need to be adapted, it's only necessary to provide HTTP access with an adaptation layer.

In a properly defined SOA architecture, a service it's composed aggregating other internal services. With the EzWeb approach, it's only necessary to wrap the service that is directly used from the user interface. Besides, it's very typical in intranets to deploy a big amount of services. However, users in their daily work, only deal with a few of them. Those very used services, are the target for being wrapped first. In the real world, not a big amount of enterprise services must be adapted to reach interesting results with EzWeb (only those which make life easier to users).

As original services are not modified, original applications keep working perfectly. Therefore, the wrapping process can be incremental.

Typical Backend scenarios

As seen before, services exported by the backend systems have to be accessible using standard HTTP requests. If existing backend systems do not export services through HTTP, we have three options:

  1. Develop a simple service (in Java, Python, PHP, ...) for each exported backend functionality. This service would be programmed to accept HTTP requests where input arguments for the service are passed, then would perform the necessary tasks in communication to the backend (a call to a process, an ODBC request, a RPC call, whatever) and finally, would return the response back (typically in JSON/XML format). Following this approach, a gadget will essentially invoke services that are wrapping backend services and exporting them through HTTP. A variant of this option would to implement a Web Service which is accessible using SOAP over http.
    JSON service example
  2. Find web pages (in the existing web portal linked to the system) you will be able to parse and extract the result values of each of the services you want to invoke. Then, for a given service, the gadget would be able to invoke the service by performing a get request using the URL linked to the web page identified for the service. The gadget would parse the returned web contents to extract the result values for the service (discarding the rest contents returned in the web page). This is not the most elegant solution, but implies no development at the server side, and in certain environments, may be adopted as a temporary solution until a solution based on approach 1 is implemented.
    HTML Clipping example
  3. Implement dedicated proxies that may transform HTTP requests made from the gadgets into whatever protocol / API invocation is supported to invoke existing backend services (e.g., a proxy which transforms HTTP requests into RPC/CORBA calls). This approach would require specification and development of a special type of proxy for each type of service invocation.

Basic Authentication API

EzWeb provides a REST API to allow third parties to interact with the EzWeb's catalogue and platform. The HTTP requests have to include the Authoritation header, following the Basic Authentication mode, in order to authenticate the user.

Each operation will be made with the data related to the user specified in the Authoritation header if the user has the necessary rights. All the operations return the status of the operation and may return a set of data in JSON format.

The available operations are:

Add a resource to the catalogue

URL: http://{host}/catalogue/API/resource
Method: POST
Parameters:
  • template_uri (POST parameter): URL of the resource template.
Response data:
  • result: Status of the operation.
  • contratable: It identifies if the resource is contratable (specified in the Contratable filed in the template).
  • templateUrl: URL of the template of the resource.
  • gadgetName: Name of the resource in the catalogue.
  • vendor: Vendor of the resource.
  • version: Version of the resource.
  • gadgetId: Identifier of the resource in the catalogue.


Delete a resource from the catalogue

URL: http://{host}/catalogue/API/resource/{resource_id}
Method: DELETE
Parameters:
  • resource_id (part of the URL): Identifier of the resource in the catalogue to be deleted.
Response data: None.

Instance a catalogue resource into the active workspace of the user

URL: http://{host}/API/gadgets
Method: POST
Parameters:
  • template_uri (POST parameter): URL of the resource template.
Response data:
  • gadget_id: Identifier of the gadget representation in the platform.
  • igadget_id: Identifier of the gadget instance in the platform.

Delete a gadget instance

URL: http://{host}/API/igadget/{igadget_id}
Method: DELETE
Parameters:
  • igadget_id (part of the URL): Identifier of the gadget instance in the platform.
Response data: None


Delete all the gadget instances related to a gadget representation

URL: http://{host}/API/gadget/{gadget_id}/igadgets
Method: DELETE
Parameters:
  • gadget_id (part of the URL): Identifier of the gadget representation in the platform.
Response data:
  • deleted_igadgets: Identifier list of the gadget instances that has been deleted.

See Also

Obtenido de "http://forge.morfeo-project.org/wiki/index.php/API"