Hello World Service¶

Hello World Service is the reference template of a SmartGears 4 service. It exposes a few REST methods that show what a service gets from SmartGears: the identity and the roles of the caller, the Context of the request, the container it runs in, the methods excluded from authorization, the errors returned to the client and a custom HTTP method.

Every method is described in the REST API documentation (ReDoc and Swagger UI), reached from the menu of these pages.

Authorization¶

D4Science adopts OIDC (OpenID Connect) for authentication and UMA 2 (User-Managed Access) for authorization. Every request carries a JSON Web Token (JWT) access token in the Authorization header:

Authorization: Bearer <token>

The token says who the caller is, in which Context the request is made and which roles the caller has there. Instructions to obtain a token are at https://dev.d4science.org/how-to-access-resources.

The paths listed under excludes in application.yaml need no token: in this service /guest and everything under it. SmartGears excludes by itself the documentation (/docs/, /api-docs/, /branding/) and its own methods under /gcube/resource/, which check their callers themselves.

Methods¶

The /auth methods are restricted with the @AuthorizationControl annotation of authorization-control-library, which answers 403 Forbidden to a caller without the role. The annotation is enforced only when the project is woven with the aspectj-maven-plugin, which the pom.xml of this template keeps commented out: without it every caller with a valid token gets the message.

PURGE is not a standard HTTP method, so it is not in the REST API documentation, which knows only the standard ones. It is widely used for this action, e.g. by Varnish. The method is declared with the @PURGE annotation of the service (jakarta.ws.rs.HttpMethod("PURGE")).

Errors¶

An error is returned with its HTTP status and a body describing it:

{
 "success": false,
 "message": "Your request is not valid",
 "result": null
}

The most common statuses are:

400 Bad Request: the request is not valid;
401 Unauthorized: the request has no token, or the token cannot be verified;
403 Forbidden: the caller lacks the role the method requires;
404 Not Found: the requested path or instance does not exist;
405 Method Not Allowed: the HTTP method is not supported for the URL; the Allow header lists the supported ones;
500 Internal Server Error: a failure of the service, to be reported in the D4Science ticketing system with the request, the time it was made and how to replicate it.

SmartGears Methods¶

As any SmartGears service, it also exposes under /gcube/resource/ the methods SmartGears adds to every application, e.g. /gcube/resource/health, /gcube/resource/metrics and /gcube/resource/lifecycle.

Postman Collection¶

The Postman collection of the service is at <service>/api-docs/postman/hello-world-service.postman_collection.json, with an example environment for /gcube/devsec/devVRE at <service>/api-docs/postman/hello-world-service-for-devvre.postman_environment.json. The environment is completed with the D4Science username and password of the user, to obtain the token.

Service Discovery in the Information System¶

SmartGears publishes the service in the Information System as an EService, identified by its SoftwareFacet. It is found with the following query, sent to the Resource Registry:

{
 "type": "EService",
 "consistsOf": [
  {
   "type": "IsIdentifiedBy",
   "target": {
    "type": "SoftwareFacet",
    "group": "org.gcube.service",
    "name": "hello-world-service"
   }
  }
 ]
}

Maven Coordinates¶

<groupId>org.gcube.service</groupId>
<artifactId>hello-world-service</artifactId>