Saltar al contenido principal
Version: próxima

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 valueDescripción
awe.rest.api.authorization-headerAuthorizationAuthentication header name
awe.rest.api.jwt.prefixBearerJWT token prefix
awe.rest.api.jwt.secret${awe.security.master.key} security propertyJWT secret password for sign token
awe.rest.api.jwt.issuerAWE ISSUERJWT issuer name
awe.rest.api.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 authenticationDescripción
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:

InputUsoTipoDescripciónValue
usernameObligatorioQuery parameterIs the user name to authenticateEx.: test
contraseñaObligatorioQuery parameterIs the user password to authenticateEx.: test

The authenticate service has the following outputs:

OutPutTipoDescripción
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:

InputUsoTipoDescripciónValue
queryIdObligatorioURI query parameterURI parameter to set the name of query in the requestEx.: UsrLst
RequestParameterOpcionalJson 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:

OutPutTipoDescripción
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:

InputUsoTipoDescripciónValue
maintainIdObligatorioURI query parameterURI parameter to set the name of maintain in the requestEx.: UsrDel
RequestParameterOpcionalJson object (body)Parameter list of query in JSON formatEx.: {"parameters": {"IdeOpe": 2} }

The maintain service has the following outputs:

OutPutTipoDescripción
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", "Bearer " + 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", "Bearer " + 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", "Bearer " + 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", "Bearer " + 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
...
}