Skip to main content
Version: Next

Rest API Module

What's a REST api? REST stands for Representational State Transfer. (It is sometimes spelled "REST".) It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

Much like Web Services, a REST service is:

  • Platform-independent (you don't care if the server is Unix, the client is a Mac, or anything else)
  • Language-independent (C# can talk to Java, etc.)
  • Standards-based (runs on top of HTTP)
  • Can easily be used in the presence of firewalls

To activate this module, follow this steps:

  • Add awe-rest dependencies to pom.xml descriptor.
<dependencies>
...
<dependency>
<groupId>com.almis.awe</groupId>
<artifactId>awe-rest-spring-boot-starter</artifactId>
</dependency>
...
</dependencies>
AWE Rest

AWE Rest configuration properties#

This module provides the following properties to overwrite the awe-rest-spring-boot-starter starter:

KeyDefault valueDescription
awe.rest.jwt.authorization-headerAuthorizationAuthentication header name
awe.rest.jwt.jwt-prefixJWT token prefix
awe.rest.jwt.jwt-secret${security.master.key} security propertyJWT secret password for sign token
awe.rest.jwt.jwt-issuerAWE ISSUERJWT issuer name
awe.rest.jwt.jwt-expiration-time60mJWT time valid token to expire

Services#

In this time AWE rest API has three services: AUTHENTICATE, QUERY and MAINTAIN group by Protected API (if it requires authentication) and Public API (if the queries or maintenance are public and do not require authentication).

AWE REST module, uses JWT (Json Web Token) as authentication method

Complete swagger documentation of awe rest services is

available here.

ServiceMethodPathRequire authenticationDescription
authenticatePOST/api/authenticatefalseUsed to authentication. Provide a JWT token to set as http header (Default value Authorization) in protected services
dataPOST/api/data/{queryId}trueUsed to launch the queries of web application. Return JSON with data query - IMPORTANT: If the query is private (needs jwt token) first you have to call /api/authenticate REST service
maintainPOST/api/maintain/{maintainId}trueUsed to launch the maintains of web application. Return JSON with maintain result - IMPORTANT: If the maintain is private (needs jwt token) first you have to call /api/authenticate REST service

Authenticate service#

The authenticate service has the following inputs:

InputUseTypeDescriptionValue
usernameRequiredQuery parameterIs the user name to authenticateEx.: test
passwordRequiredQuery parameterIs the user password to authenticateEx.: test

The authenticate service has the following outputs:

OutPutTypeDescription
usernameStringIs the user name for which the token has been generated.
tokenStringIs the jwt token. Used to authentication process. Note: If you want call /api/data or /api/maintain rest api, you have to send this parameter as http header in the request
issuerStringIs the jwt issuer
expiresAtDateTimeExpiration time of jwt token

Note: The output is in JSON format

This is example of json output

{
"expiresAt": "2021-04-26T16:16:18.000+00:00",
"issuer": "AWE issuer",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0IiwiaXNzIjoiQVdFIElTU1VFUiIsImV4cCI6MT",
"username": "foo"
}

Query service#

The data service has the following inputs:

InputUseTypeDescriptionValue
queryIdRequiredURI query parameterURI parameter to set the name of query in the requestEx.: UsrLst
RequestParameterOptionalJson object (body)Parameter list of query in JSON formatEx.: {"parameters": {"parName1": "value1","parName2": "value2","parName3": ["valueList1","valueList2","valueList3"]}}

The data service has the following outputs:

OutPutTypeDescription
typeStringResult of operation (ok, info, warning, error)
titleStringTitle of response
messageStringMessage response
dataListJson objectData result of query service

Note: The output is in JSON format

Maintain service#

The maintain service as POST has the following inputs:

InputUseTypeDescriptionValue
maintainIdRequiredURI query parameterURI parameter to set the name of maintain in the requestEx.: UsrDel
RequestParameterOptionalJson object (body)Parameter list of query in JSON formatEx.: {"parameters": {"IdeOpe": 2} }

The maintain service has the following outputs:

OutPutTypeDescription
typeStringResult of operation (ok, info, warning, error)
titleStringTitle of response
messageStringMessage response
resultDetailsJson objectMaintain result details

Note: The output is in JSON format

Client API Rest examples#

  • Login client example
// Authenticate
@Test
public void authenticateUser() {
// Init rest template
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
// Build authenticate request
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("http://localhost:8080/api/authenticate"))
.queryParam("username","test")
.queryParam("password","test");
HttpEntity<String> entity = new HttpEntity<>(headers);
ResponseEntity<LoginResponse> response = restTemplate.exchange(
builder.toUriString(),
HttpMethod.POST,
entity,
LoginResponse.class);
// LoginResponse has token info
...
}
  • Data client example
// Data without parameters
@Test
public void protectedQueryAuthorized() {
// Init rest template
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
String queryId = "query";
//Authenticate user (call /api/authenticate to get jwt token)
headers.add("Authorization", jwtToken);
HttpEntity<String> entity = new HttpEntity<>(headers);
ResponseEntity<AweRestResponse> response = restTemplate.exchange("http://localhost:8080/api/data/" + queryId,
HttpMethod.POST,
entity,
AweRestResponse.class);
// AweRestResponse has response info
...
}
// Data with parameters
@Test
public void protectedQueryParametersAuthorized() {
// Init rest template
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
String queryId = "query";
//Authenticate user (call /api/authenticate to get jwt token)
headers.add("Authorization", jwtToken);
// Build parameters request
headers.setContentType(MediaType.APPLICATION_JSON);
RequestParameter parameters = new RequestParameter();
Map<String, Object> paramMap = new HashMap<>();
paramMap.put("param1", 1);
paramMap.put("param2", "value2");
paramMap.put("param3", Arrays.asList("value1", "value2"));
parameters.setParameters(paramMap);
HttpEntity<RequestParameter> entity = new HttpEntity<>(parameters, headers);
ResponseEntity<AweRestResponse> response = restTemplate.exchange("http://localhost:8080/api/data/" + queryId,
HttpMethod.POST,
entity,
AweRestResponse.class);
// AweRestResponse has response info
...
}
  • Maintain client example
// Maintain without parameters
@Test
public void protectedMaintainAuthorized() {
// Init rest template
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
String maintainId = "MAINTAIN";
//Authenticate user (call /api/authenticate to get jwt token)
headers.add("Authorization", jwtToken);
HttpEntity<String> entity = new HttpEntity<>(headers);
ResponseEntity<AweRestResponse> response = restTemplate.exchange("http://localhost:8080/api/maintain/" + maintainId,
HttpMethod.POST,
entity,
AweRestResponse.class);
// AweRestResponse has response of maintain result
...
}
// Maintain with parameters
@Test
public void protectedMaintainParametersAuthorized() {
// Init rest template
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
String maintainId = "MAINTAIN";
// Build parameters request
headers.setContentType(MediaType.APPLICATION_JSON);
RequestParameter parameters = new RequestParameter();
Map<String, Object> paramMap = new HashMap<>();
paramMap.put("userId", 1);
parameters.setParameters(paramMap);
//Authenticate user (call /api/authenticate to get jwt token)
headers.add("Authorization", jwtToken);
HttpEntity<RequestParameter> entity = new HttpEntity<>(parameters, headers);
ResponseEntity<AweRestResponse> response = restTemplate.exchange("http://localhost:8080/api/maintain/" + maintainId,
HttpMethod.POST,
entity,
AweRestResponse.class);
// AweRestResponse has response of maintain result
...
}