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.ini) and a token of the node’s working Context, the shallowest Context the client holds. The service therefore:

grants POST /record to the node clients;
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.
500 Internal Server Error: the body is not a valid list of records, or the service failed; the body of the response is a text message. 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.

Service Maven Coordinates¶

The Maven coordinates of the Accounting Service are:

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