Welcome to gCube Accounting Service documentation¶

The Accounting Service receives the accounting records of the D4Science infrastructure and stores them in the accounting database. Every SmartGears node accounts the usage of its services through the accounting libraries, which send the records to this service; the service harmonises them and writes them into the database (TimescaleDB, a PostgreSQL extension).

See the REST API documentation.

Base URL¶

In the production environment, its current value is https://accounting-service.d4science.org/accounting-service

Authorization¶

D4Science adopts OIDC (OpenID Connect) for authentication and authorization; every request carries a JSON Web Token (JWT) access token in the Authorization: Bearer HTTP header.

Obtain your Bearer token here: https://dev.d4science.org/how-to-access-resources

A request without a token, or with a token that cannot be verified, is refused with 401 Unauthorized.

Contract with the accounting libraries¶

The records are sent by document-store-lib-accounting-service, the backend of every SmartGears node, with the OIDC client of the node (dsl.yaml) and a token of the node's working Context, the shallowest Context the client holds. The service therefore:

grants POST /record to clients only: a token of a user is refused with 403 Forbidden;
accepts a record whose scope differs from the Context of the token: the two are not compared, the record is stored with its own scope.

A check that compared them would send every record of the other Contexts to the fallback file of the nodes.

Operations¶

The service has one operation:

Operation	HTTP Method	URL	Success HTTP Status	Safe	Idempotent
Account records	POST	/record	201 Created	N	Y

It is idempotent because every record carries its own identifier and the database ignores a record whose identifier is already stored: sending the same records again does not account them twice.

The body is a JSON array of records, as the accounting libraries serialise them, sent with Content-Type: application/json.

HTTP Statuses¶

201 Created: the records are accepted. The accounting library of the service buffers them and writes them into the database shortly afterwards; a record it cannot write goes to its fallback file and is written again later.
401 Unauthorized: the request carries no token, or one that cannot be verified.
403 Forbidden: the token is not one of a client; only the clients of the SmartGears nodes send records.
400 Bad Request: the body is not a valid list of records; the body of the response is a short text message.
500 Internal Server Error: the service failed; the body of the response is a generic text message, and the details are in the log of the service. Please report a failure in the gCube ticketing system, with the time of the request.

Service Discovery on IS¶

The service is an EService of the Information System, identified by its SoftwareFacet:

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

The accounting libraries find it with the Query Template gcube-eservice-accesspoint-by-group-and-name.

Public Statistics¶

The landing page of the service and /smartgears/accounting-service/statistics give, without a token, totals computed from the accounting database. They are aggregate numbers only: nothing is given by Context, by user or by calling host.

Group	Figures	Computed every
Calls to the Services	the calls held, by result (success, failure), in the last 30 days; the first and the last record	30 minutes
Operations on the Storage	the operations held, by type (create, read, update, delete)	30 minutes
Job Executions	the executions held	30 minutes
Coverage	the services and the nodes with records, the calls by year	1 hour

The volumes of the storage operations are not summed into the space in use: the records do not start from the initial content of the storage.

Service Maven Coordinates¶

The Maven coordinates of the Accounting Service are:

<groupId>org.gcube.accounting</groupId>
<artifactId>accounting-service</artifactId>