Introduction to REST and RestHUB  1. REST ­ Representational State Transfer  1.1. Overview ­ What is REST?  REST  is  an  architectural  style  which  is  based  on  web­standards  and  the  HTTP  protocol.  REST was first described by Roy Fielding in 2000.  In  a  REST  based  architecture  everything  is  a  resource.  A  resource  is  accessed  via  a  common interface based on the HTTP standard methods.  In  a  REST  based  architecture  you  typically  have   a  REST  server  which  provides  access  to  the resources and a REST client which accesses and modifies the REST resources.  Every  resource  should  support  the  HTTP  common  operations.  Resources  are  identified  by  global IDs (which are typically URIs).  REST  allows  that  resources  have  different  representations,  e.g.,  text,  XML,  JSON  etc.  The  REST  client  can  ask  for  a  specific  representation  via  the  HTTP  protocol  (content  negotiation). 

1.2. HTTP methods  The ​ PUT​ , ​ GET​ , ​ POST​  and ​ DELETE​  methods are typically used in REST based  architectures.  The following table gives an explanation of these operations.  ●

GET defines a reading access of the resource without side­effects. The resource is  never changed via a GET request, e.g., the request has no side effects (idempotent). 



PUT creates a new resource. It must also be idempotent. 



DELETE removes the resources. The operations are idempotent. They can get  repeated without leading to different results. 



POST updates an existing resource or creates a new resource. 

1.3. RESTFul web services  A RESTFul web services are based on HTTP methods and the concept of REST. A  RESTFul web service typically defines the base URI for the services, the supported  MIME­types (XML, text, JSON, user­defined, ...) and the set of operations (POST, GET,  PUT, DELETE) which are supported.   

2. RestHUB ­ RESTful API for Oracle DB querying  2.1. Overview  RestHub was designed to provide a way to access data from the client application through  RESTful API. In this manner developers will no longer have to implement difficult  approaches for data retrieval from the database in representational layer and can separate  application and representation codebase. They will be able to access data through the  RestHub system by sending simple SQL queries. 

2.2. Benefits  ●

Separate data access from the representation  ○

Data access via API 



Application and representation on separate codebase 



Standard, reusable API 



Many ways to use the service (Browser, Python, Java, JS, ...) 

 

 

2.3. Features  Self descriptive:  ●

Includes metadata 



HATEOAS (including hypermedia links with the responses). 

Secure:  ●

Specialized multilevel query parsers 



Multithreading 



Timeouts 

Fast:  ●

Caching 



Asynchronous prefetching 

Flexible:  ●

SQL for querying 

2.4. Types of resources  ●

Tables: Views with optional parameters and metadata, back­end control. 



Queries: Views on Tables, front­end control. 



Cache: Query result in different representation for fast retrieval. 

 

2.5. RestHub raw API  This API is mainly used by RestHub plugins. Developers that want to use RestHub should use  those plugins instead of this API. Plugins are described below.  Variables:  ● {namespace} ­ group of tables  ● {name} ­ table name  ● {id} ­ ​ automatically generated id number (via POST method)    URL 

Method 

Description 

/tables 

GET 

List of tables in JSON 

/table/{namespace} 

GET 

List of single namespace tables in JSON 

/table/{namespace}/{name} 

GET 

Table description in JSON 

/queries 

GET 

List of queries in JSON 

/query 

POST  

Create query from provided entity SQL and  return automatically generated {id} 

/query/{id}  

GET 

Query description in JSON 

/query/{id} 

DELETE 

Remove query 

/query/{id}/data?{r}={v} 

GET 

Get query data. Media type is by Accept  header. For example:  “Accept” : “application/xml”. Variables: r  ­  parameter name, v ­ parameter value. 

/query/{id}/page/{pp}/{p}/data?{r }={v} 

GET 

Get query page data. Media type is by  Accept header. Variables:  pp ­ data rows per page, p ­ page number, r  ­ parameter name, v ­ parameter value. 

/table/{namespace}/{table}/data ?{r}={v} 

GET 

Get table data. Media type is by Accept  header. For example: “Accept” :  “application/xml”. Creates query and  redirects to it. Variables: r  ­ parameter  name, v ­ parameter value. 

/table/{namespace}/{table}/page /{pp}/{p}/data?{r}={v} 

GET 

Get query page data. Media type is by  Accept header. Variables: pp ­ data rows per  page, p ­ page number, r  ­ parameter name,  v ­ parameter value. Creates query and  redirects to it. 

/query/{id}/cache 

GET 

Get query cache information 

/query/{id}/cache 

DELETE 

Clean all query cache 

/table/{namespace}/{name}/cac

GET 

Get the list of query caches that use the 

he   /blacklist 

table defined  GET 

List of blacklisted tables in JSON 

/blacklist/{namespace} 

GET 

List of blacklisted namespace tables in JSON 

/blacklist/{namespace}/{name} 

GET 

Blacklisted table description in JSON 

/blacklist 

DELETE 

Remove all tables from blacklist (refresh) 

/blacklist/{namespace} 

DELETE 

Remove all namespace tables from blacklist  (refresh) 

/blacklist/{namespace}/{name} 

DELETE 

Remove table from blacklist (refresh) 

/info 

GET 

General information about the service 

 

3. RestHUB Tutorial ­ How to use it  3.1. Store your tables in RestHub  In  order  to  start  using  RestHub  you  have  to  create  an  XML  file  where  your  database  tables  would  be  stored.  This  file  should  be  created  from   the  template  and  put  in  application  classpath.  When  this  XML  file is  uploaded to svn versioning system it is automatically  picked  up  by  the  RestHub  and  all  the  necessary  tables  are  created  and  saved. From this point you  are ready to use RestHub in your applications.    Example  of  simplified  tables  XML  file  is  listed  below.  There  is  only  one  table  (hcal_parts) in  this example, but it’s possible to add as many tables as you need. 
CACHE_TIME​ ​ =​ "120"

HIT_COUNT​ ​ =​ "1"

TIME_OUT​ ​ =​ "30"

ROWS_LIMIT​ ​ =​ "1000"

CONNECTION_NAME​ =​ "default"> ​ Unique list of notebook parts​ ​ ​ hcal​ hcal_​ ​ parts​ ​SELECT DISTINCT ​ P.PART_ID, P.NAME_LABEL

FROM​CMS_HCL_CORE_CONSTRUCT​ .​ PARTS P ​ ​ Part ID​ ​ ​ PART_ID​ ​ ​ STRING​ ​ Part name​ ​ ​ NAME_LABEL​ ​ ​ STRING​

  ​


Table has several options. The most important are listed below:  ●

CACHE_TIME ­ RestHub will save query data in cache for 120 seconds. 



ROWS_LIMIT ­ the maximum number of data rows returned from one query. 



CONNECTION_NAME  ­  there  can  be  multiple  connections  to  the  database(s)  which  are identified by name. 

   

 

3.2. RestHub Javascript plugin   For  example  we  want  to  create  a simple  HTML + Javascript page. There are several plugins  already  created  that  will  help  us.  We  have  to  put  them  in  our   page  directory  and  (or)  to  include a path to those plugins.   A brief description of plugins:  ●

rhserver.js ­ this file stores a path to RestHub machine. 



resthub.js ­ main plugin that will help us to use RestHub. 



resthub.table.js ­ plugin that draws a table and uses RestHub. 

All these plugins are created with jQuery library. So we have to include it as well.  If we are using Java language for our application there are also similar plugins created. 

  3.2.1 resthub.js API  Before  using  resthub.js  plugin  we  have  to  make  sure  that  a  variable  called  rhserver  in  rhserver.js points to RestHub machine. We would use reshub.js API through this variable.  Consumer API:  ●

rhserver.query(sql)  ­  assigns  sql  to   a  query.  Later  on  if  we  want  to  modify   a  specific   query we could change sql and refresh it like this: 





rhserver.query.sql += “ ORDER BY someColumn ASC” ; 



rhserver.query.refresh(); 

rhserver.data() ­ executes query and returns data. This method has parameters:  ○

type ­ content type (json, xml, ... ) 



ppage  ­ data rows per page 



page ­ page number 



params  ­  query  SQL  parameters.  Parameter  name  in  SQL  should  begin  with  :  symbol, for example :parameter. 

Example:   var​q ​ =​rhserver​ .​ query​ (​ "SELECT * FROM hcal.hcal_parts q WHERE q.PART_ID = :part_id"​ ); var​query_data ​ =​q​ .​ data​ ({​type​ :​​ "application/xml"​ ,​ ppage​ :​​ 20​ , page​ :​​ 5​ ,​​ params​ :​​ {​ part_id​ :​​ 5​ }});

  3.2.2 resthub.table.js API  This  plugin  draws  a  datatable  to  a  specific  div  element  by  passing  a  query  and  various  parameters  to  it.  It  was  made  by  implementing  datatables  (​ http://datatables.net​ )  and  resthub.js   plugins.  To  use  it  we  just  have  to  select  (through   jQuery  selectors)  a  specific  div  and then call rhTable method with parameters. Parameter descriptions:  ●

query ­ assign a query 



params ­ query parameters 



showColumns ­ how many columns you want to show on a table. Others will be hidden 



tableOptions ­ various table options (more info on ​ http://datatables.net​  ). 

Example:   // Variable that stores datatable option - to add a link on ID column var​tableOptions ​ =​{ "fnRowCallback"​ :​​ function​ (​ nRow​ ,​aData​ ,​iDisplayIndex​ )​{ $​ (​ 'td:eq(0)'​ ,​nRow​ ).​ html​ (​ ''​​ + aData​ [​ 0​ ]​​ +​​ ''​ ); return​nRow; ​ } }; // assign a query to variable q var​q ​ =​rhserver​ .​ query​ (​ "SELECT * FROM hcal.hcal_parts q WHERE q.PART_ID = :part_id"​ ); // draw a table to a ​ hcal_parts_table div $​ (​ '#​ hcal_parts_table​ ).​ rhTable​ ({​ query​ : q, ​ params​ : {part_id: 5}, ​ showColumns​ : 5, tableOptions​ : tableOptions});  

3.3. Building a simple web page that uses RestHub  Now  that  we  know  how  to  use  resthub  plugins  we   can  start  coding our applications.  Here is  the code for a simple page that displays a datatable from querying hcal_part table:  ​ ​ ​ HCAL example​ @import​​ ​ "css/themes/smoothness/jquery-ui-1.8.4.custom.css"; ​   $​ (​ document​ ).​ ready​ (​ function​ ()​{

​/ specify a query to RestHub / var​q ​ ​ =​rhserver​ .​ query​ (​ "SELECT * FROM hcal.hcal_parts c"​ ); // draw a table using this query ​ $​ (​ '#​ hcal_parts_table​ ).​ rhTable​ ({​ query​ :​q​ });

}); ​ ​/script> < ​

​ ​ HCAL parts table​

​ ​

  3.4. RestHub Java plugin  If  we  want  to  create  a  Java  application  that  uses  Resthub  there are several classes that will  help us. We have to put them in our classpath and import them:   import​net​ .​ resthub​ .​ client​ .​ RestHubServer; import​net​ .​ resthub​ .​ model​ .​ DataResponse; import​net​ .​ resthub​ .​ model​ .​ QueryManager; 

The usage of these plugins are very similar to earlier described jQuery plugins.  Example:  // this class stores a path to RestHub machine. RestHubServer​rh ​ =​​ new​​ RestHubServer​ (​ "​ http://localhost:8080/api​ "​ ); // assign sql to a query QueryManager qm ​ = rh​ .​ newQueryManager​ (​ "SELECT * FROM hcal.hcal_parts q WHERE q.PART_ID = :part_id"​ ); qm​ .​ addParameter​ (​ "part_id"​ ,​​ 5​ ); // executes query and returns data DataResponse​dr ​ =​qm​ .​ getData​ (​ "application/xml"​ ); 

4. How to start the service  Resthub application is based on the Restlet framework so Resthub is a normal Restlet  Application (​ org.restlet.Application​ ) which can be easily integrated into your backend  application stack. The easiest way to start the application is to start it from the main method,  i.e.   

private​​ static​​ final​​ int​PORT ​ =​someport; public​​ static​​ void​main​ (​ String​ []​args​ )​​ throws​​ Exception​{ ConnectionFactory​cf ​ =​​ new​​ MyConnectionFactory​ (); TableFactory​tf ​ =​​ new​​ MyTableFactory​ (); ServerApp​app ​ =​​ new​​ ServerApp​ (​ cf​ ,​tf​ ); Component​comp ​ =​​ new​​ Component​ (); comp​ .​ getServers​ ().​ add​ (​ Protocol​ .​ HTTP​ ,​PORT​ ); comp​ .​ getDefaultHost​ ().​ attach​ (​ app​ ); comp​ .​ start​ ();



  This starts the RestHub service on PORT. Of course, you have to implement your  net.resthub.ConnectionFactory and net.resthub.TableFactory interfaces which provide access  to Oracle databases (aka connections) and tables metadata. We provide  net.resthub.factory.DbTableFactory which extracts metadata from the Oracle database and  net.resthub.factory.XmlClasspathFactory which extracts metadata from XML files in the  classpath.   

5. How to write queries  RestHub queries are simple SQL statements to combine tables into the single output.   Limitations:  ­

tables referred by namespace.table 

­

all tables used must have the unique alias in a query 

­

only tables that share the same connection can be used in a query 

­

named parameters are supported, i.e. :name 

­

by default named parameter is considered of string type 

­

named parameter type can be changed with prefix: 

­

­

s__{parameter name} ­ string type, i.e. s__name, s__country 

­

n__{parameter name} ­ number type, i.e. n__id, n__voltage 

­

d__{parameter name} ­ date type, i.e. d__from, d__to 

supported functions can be found under /info 

Example queries:  select * from shop.customers c select * from shop.customers c order by c.name

select c.* from shop.customers c, shop.sales s where c.id = s.customer_id order by s.sale_date select c.name, s.sale_date from shop.customers c join shop.sales s on c.id = s.customer_id order by s.sale_date select c.name, s.sale_date from shop.customers c join shop.sales s on c.id = s.customer_id where c.country = ‘USA’ order by s.sale_date select c.name, s.sale_date from shop.customers c join shop.sales s on c.id = s.customer_id where c.country = :country order by s.sale_date // parameter ?country=USA select c.name, s.sale_date from shop.customers c join shop.sales s on c.id = s.customer_id where c.country = :s__country order by s.sale_date // parameter ?country=USA select c.name, s.sale_date from shop.customers c join shop.sales s on c.id = s.customer_id where s.price >= :n__price_from and s.price <= :n__price_to order by s.sale_date // parameter ?price_from=10&price_to=100

     

Introduction to REST and RestHUB - GitHub

2. RestHUBанаRESTful API for Oracle DB querying. 2.1. Overview. RestHub was designed .... For example we want to create a simple HTML + Javascript page.

239KB Sizes 6 Downloads 365 Views

Recommend Documents

C# Anleitung - REST + Klienten - GitHub
"Data Source=(localdb)\\v11.0;Initial Catalog=MusicDb;Integrated Security=True" .... Name = "Gordon Goodwin Big Phat Band",. Songs = new List().

Introduction to Algorithms - GitHub
Each cut is free. The management of Serling ..... scalar multiplications to compute the 100 50 matrix product A2A3, plus another. 10 100 50 D 50,000 scalar ..... Optimal substructure varies across problem domains in two ways: 1. how many ...

Introduction to R - GitHub
Nov 30, 2015 - 6 Next steps ... equals, ==, for equality comparison. .... invoked with some number of positional arguments, which are always given, plus some ...

Introduction To DCA - GitHub
Maximum-Entropy Probability Model. Joint & Conditional Entropy. Joint & Conditional Entropy. • Joint Entropy: H(X,Y ). • Conditional Entropy: H(Y |X). H(X,Y ) ...

Using the Xtivia Services Framework (XSF) to Create REST ... - GitHub
As we know the current trend in web application development is toward Single Page Applications (SPAs), where the majority of application functionality is ...

Chatter REST API Developer Overview - GitHub
Building an application outside the Salesforce platform. • Pull feed and social graph out into another application. • Push notifications and activity into the feed.

Instant REST Services With RestExpress - GitHub
Any session state is held on the client. Client-Server. • Assume a disconnected system. • Separation of concerns. • Uniform interface links the two ...

Introduction to phylogenetics using - GitHub
Oct 6, 2016 - 2.2 Building trees . ... Limitations: no model comparison (can't test for the 'best' tree, or the 'best' model of evolution); may be .... more efficient data reduction can be achieved using the bit-level coding of polymorphic sites ....

Introduction to Fluid Simulation - GitHub
upon the notes for a Siggraph course on Fluid Simulation[Bridson. 2007]. I also used .... “At each time step all the fluid properties are moved by the flow field u.

122COM: Introduction to C++ - GitHub
All students are expected to learn some C++. .... Going to be learning C++ (approved. ). ..... Computer Science - C++ provides direct memory access, allowing.

Introduction to NumPy arrays - GitHub
www.scipy-lectures.org. Python. Matplotlib. SciKits. Numpy. SciPy. IPython. IP[y]:. Cython. 2015 ..... numbers and determine the fraction of pairs which has ... origin as a function of time. 3. Plot the variance of the trajectories as a function of t

An Introduction to BigQuery - GitHub
The ISB-CGC platform includes an interactive Web App, over a Petabyte of TCGA data in Google Genomics and Cloud Storage, and tutorials and code ...

Introduction to NumPy arrays - GitHub
we want our code to run fast. ▷ we want support for linear algebra ... 7. 8 a[0:5] a[5:8]. ▷ if step=1. ▷ slice contains the elements start to stop-1 .... Indexing and slicing in higher dimensions. 0. 8. 16. 24. 32. 1. 9. 17. 25. 33. 2. 10. 18.

Introduction to Framework One - GitHub
Introduction to Framework One [email protected] ... Event Management, Logging, Caching, . ... Extend framework.cfc in your Application.cfc. 3. Done. (or in the ... All controllers are passed the argument rc containing the request.context, and all v

introduction - GitHub
warehouse to assemble himself. Pain-staking and time-consuming... almost like building your own base container images. This piggy purchased high- quality ...

Introduction - GitHub
software to automate routine labor, understand speech or images, make diagnoses ..... Shaded boxes indicate components that are able to learn from data. 10 ...... is now used by many top technology companies including Google, Microsoft,.

Introduction - GitHub
data. There are many ways to learn functions, but one particularly elegant way is ... data helps to guard against over-fitting. .... Gaussian processes for big data.

Introduction - GitHub
For the case that your PDF viewer does not support this, there is a list of all the descriptions on ...... 10. Other Formats. 10.1. AMS-TEX. AMS-TEX2.0. A macro package provided by the American .... A TeX Live port for Android OS. Based on ...

Introduction - GitHub
them each year. In an aggregate travel demand model, this would be represented as 100/365.25 = 0.2737851 trucks per day. In the simulation by contrast, this is represented as ... based on the distance traveled (Table 3.3). 2FAF3 Freight Traffic Analy

Course: Introduction to Intelligent Transportation Systems - GitHub
... Introduction to Intelligent Transportation Systems. University of Tartu, Institute of Computer Science. Project: Automatic Plate Number. Recognition (APNR).

Introduction to Handibot Software and Handibot Apps I. Hello ... - GitHub
describing the new “FabMo” software platform that runs the tools. ... as a methodology because we believe it is an effective way for small companies, ..... Page 10 ...

A Beginner's Introduction to CoffeeKup - GitHub
the buffer, then calls the title function which adds it s own HTML to the buffer, and ... Now it is starting to look like real HTML you d find on an ugly web page. 2 ...

Introduction to RestKit Blake Watters - GitHub
Sep 14, 2011 - Multi-part params via RKParams. RKParams* params = [RKParams paramsWithDictionary:paramsDictionary];. NSData* imageData .... This is typically configured as a secondary target on your project. // Dump your seed data out of your backend

Introduction to Scientific Computing in Python - GitHub
Apr 16, 2016 - 1 Introduction to scientific computing with Python ...... Support for multiple parallel back-end processes, that can run on computing clusters or cloud services .... system, file I/O, string management, network communication, and ...