Difference between revisions of "GxRest"

From Gcube Wiki
Jump to: navigation, search
(Exploitation)
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
== About REST ==
 +
Basically, REST is an architecture you can use when calling APIs or making APIs available to be called. It is independent of what's happening on either side, and what other software is being used when sending or receiving the REST calls. You can write an application that runs on a Mac, Windows, Linux, an Android phone or tablet, iPhone, iPod, or web site, and use the same REST API for all of those platforms. Data can be passed in and/or out when the REST API is called. The REST API doesn't care from what platform it's called – what's important is the information passed in the request and the data provided in the response.
 +
 
== Goals and Principles ==
 
== Goals and Principles ==
The gCube eXtensions to the Rest Protocol (gxRest) is a Java library designed to provide convenient round-trip interaction between a Restful web application and its clients.  
+
The gCube eXtensions to the REST Protocol (gxRest) is set if Java libraries designed to provide convenient round-trip interaction between a Restful web application (also known as "service") and its clients.  
 
   
 
   
The library is consistently divided in:
 
* context-aware [[GxRest/Requests | requests]] sent from a client to a web application
 
* outbound status-aware [[GxRest/Responses#Outbound_Responses | responses]] returned from a web application
 
* inbound [[GxRest/Responses#Inbound_Responses | responses]] received by a client.
 
 
Prominent features of the library are:
 
* to achieve independence from the web framework used to develop the web application;
 
* to guarantee the correctness of requests/responses across the D4Science infrastructure;
 
* to abstract over the HTTP-based details required by the gCube framework when invoking a remote service;
 
* to avoid that each service implements its own conventions over the returned responses;
 
* to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams.
 
 
 
== Exploitation ==
 
== Exploitation ==
 
gxRest has the flexibility for different degrees of exploitation of the library:
 
gxRest has the flexibility for different degrees of exploitation of the library:
Line 20: Line 11:
 
* it can be used to parse the [https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP code] of a response;
 
* it can be used to parse the [https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP code] of a response;
 
* it can be used only to return HTTP codes from the service.
 
* it can be used only to return HTTP codes from the service.
 +
* it can be used only to return Exceptions from the service.
  
== Correlation with the JAX-RS runtime ==
+
== Module: gxHTTP ==
The gxRest approach is independent from the [https://jcp.org/en/jsr/detail?id=311 JAX-RS] implementation used to develop the web application, being entirely based on the <code lang="Java">javax.ws.rs</code> package. However, some features rely on a JAX-RS runtime implementation. It dynamically loads the implementation available on the classpath and uses it for modeling and sending the responses and requests. The reference implementation for JAX-RS is named [http://jersey.java.net/ Jersey], but it is not included in Java SE. You must explicitly add Jersey or another JAR-RS implementation to your classpath.
+
[[GxRest/GxHTTP|gxHTTP]] defines the HTTP interface for a client of a gCube service and basic extensions to plain HTTP requests with zero-dependencies.  
 +
More specifically, it help create context-aware requests sent from a client to a web application. No support for managing responses both at service and client side is provided.
  
At request side, a JAX-RS runtime is not strictly required as one of the requests implementation builds atop of plain HTTP protocol.
+
== Module: gxJRS ==
 +
[[GxRest/GxJRS|gxJRS]] is much more advanced than gxHTTP and offers fully-fledged extensions built on top of JAX-RS and gxHTTP.  
  
== Integration with the client libraries of FWS ==
+
Prominent features of gxJRS are:
gxRest integrates very easily with the [[ Integration_and_Interoperability_Facilities_Framework | client libraries]] (common-jaxrs-client, common-clients) of the FeatherWeight Stack by providing a request (<code>GXWebTargetAdapterRequest</code>) fully compatible with <code>javax.ws.rs.client.WebTarget</code>. The integration is described in a [[GxRest/Requests#How_to_integrate_with_the_FeatherWeight_Stack | dedicate section]] of the request page.
+
* to achieve independence from the web framework used to develop the web application;
 +
* to guarantee the correctness of requests/responses across the D4Science infrastructure;
 +
* to abstract over the HTTP-based details required by the gCube framework when invoking a remote service;
 +
* to avoid that each service implements its own conventions over the returned responses;
 +
* to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams.
  
== Distribution ==
+
== Integration with the client libraries of FWS ==
gxRest is available as Maven artifact and can be added to a project with the following coordinates:
+
gxRest smoothly integrates with the [[ Integration_and_Interoperability_Facilities_Framework | client libraries]] (common-jaxrs-client, common-clients) of the FeatherWeight Stack by providing a request (<code>GXWebTargetAdapterRequest</code>) fully compatible with <code>javax.ws.rs.client.WebTarget</code>. The integration is described in a [[GxRest/Requests#How_to_integrate_with_the_FeatherWeight_Stack | dedicate section]] of the request page.
<source lang="xml">
+
<dependency>
+
<groupId>org.gcube.common</groupId>
+
<artifactId>gxRest</artifactId>
+
<version>0.0.2-SNAPSHOT</version>
+
</dependency>
+
</source>
+

Latest revision as of 20:17, 24 April 2019

About REST

Basically, REST is an architecture you can use when calling APIs or making APIs available to be called. It is independent of what's happening on either side, and what other software is being used when sending or receiving the REST calls. You can write an application that runs on a Mac, Windows, Linux, an Android phone or tablet, iPhone, iPod, or web site, and use the same REST API for all of those platforms. Data can be passed in and/or out when the REST API is called. The REST API doesn't care from what platform it's called – what's important is the information passed in the request and the data provided in the response.

Goals and Principles

The gCube eXtensions to the REST Protocol (gxRest) is set if Java libraries designed to provide convenient round-trip interaction between a Restful web application (also known as "service") and its clients.

Exploitation

gxRest has the flexibility for different degrees of exploitation of the library:

  • it can be entirely adopted both at client and service side with full benefit of its conventions;
  • it can be used just to send REST requests based only on plain HTTP;
  • it can be used to parse the HTTP code of a response;
  • it can be used only to return HTTP codes from the service.
  • it can be used only to return Exceptions from the service.

Module: gxHTTP

gxHTTP defines the HTTP interface for a client of a gCube service and basic extensions to plain HTTP requests with zero-dependencies. More specifically, it help create context-aware requests sent from a client to a web application. No support for managing responses both at service and client side is provided.

Module: gxJRS

gxJRS is much more advanced than gxHTTP and offers fully-fledged extensions built on top of JAX-RS and gxHTTP.

Prominent features of gxJRS are:

  • to achieve independence from the web framework used to develop the web application;
  • to guarantee the correctness of requests/responses across the D4Science infrastructure;
  • to abstract over the HTTP-based details required by the gCube framework when invoking a remote service;
  • to avoid that each service implements its own conventions over the returned responses;
  • to return error responses at the familiar (for any Java programmer) level of exceptions and error codes, while web frameworks usually just let return an HTTP status, headers and streams.

Integration with the client libraries of FWS

gxRest smoothly integrates with the client libraries (common-jaxrs-client, common-clients) of the FeatherWeight Stack by providing a request (GXWebTargetAdapterRequest) fully compatible with javax.ws.rs.client.WebTarget. The integration is described in a dedicate section of the request page.