# 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](../api-docs/index.html).

## Base URL

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

## Authorization

D4Science adopts [OIDC (OpenID Connect)](https://openid.net/connect) for authentication and
authorization; every request carries a [JSON Web Token (JWT)](https://jwt.io/) 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](https://support.d4science.org), with the time of the request.

## Service Discovery on IS

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

```json
{
  "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:

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