Author: Serż Minus

# MToken REST API

This REST MToken web service allows you to work with a remote repository for your tarballs. This service supports the publication and storage of your tarballs, allows you to download any stored tarball at any time, and also allows you to delete (revoke) unnecessary tarballs. The tarball files (tarballs) is a snapshots of your token devices which was encrypted of your public PGP key.

To work with the service, you need to use the mtoken program, it allows you to perform all basic operations with tarballs and also allows you to compare tarballs with each other

Tarball file format: `C%Y%m%dT%H%M%S.tkn`

- `%Y` The year as a decimal number including the century
- `%m` The minute as a decimal number (range 00 to 59)
- `%d` The day of the month as a decimal number (range 01 to 31)
- `%H` The hour as a decimal number using a 24-hour clock (range 00 to 23)
- `%M` The minute as a decimal number (range 00 to 59)
- `%S` The second as a decimal number (range 00 to 60)

See also strftime(3) man page for more

## GET /mtoken

Returns information about repository and shows list of stored token-folders (branches)

    curl -v --insecure https://admin:admin@localhost:8642/mtoken

    > GET /mtoken HTTP/1.1
    > Host: localhost:8642
    > Authorization: Basic YWRtaW46YWRtaW4=
    > User-Agent: curl/7.68.0
    > Accept: */*
    >

    < HTTP/1.1 200 OK
    < Content-Length: 347
    < Content-Type: application/json
    < Server: MToken/1.03
    < Date: Sat, 09 Oct 2021 05:59:52 GMT
    <

    {
        "generated": "2021-10-09 05:57:39 GMT",
        "message": "Ok",
        "tokens": ["test","bar","foo"]
    }

Format of the JSON response:

- `generated` is date of response in GMT [optioanal]
- `message` is a response message or text of error
- `tokens` is array of the token names [optional]

## PUT /mtoken/<TOKEN_NAME>/<TARBALL_FILE.tkn>

Performs commit operation. Uploading tarball file (TARBALL_FILE.tkn) to repository for token (TOKEN_NAME)

    curl -v --insecure -X PUT -F size=20210 \
      -F md5=ede8216798c1649c79e70ac69f2f6e7a -F tarball=@C20211009T090718.tkn \
      https://admin:admin@localhost:8642/mtoken/test/C20211009T090718.tkn

    > PUT /mtoken/test/C20211009T090718.tkn HTTP/1.1
    > Host: localhost:8642
    > Authorization: Basic YWRtaW46YWRtaW4=
    > Content-Type: multipart/form-data; boundary=KqfJX
    > User-Agent: curl/7.68.0
    > Content-Length: 20466
    >

    < Content-Length: 120
    < Date: Sat, 09 Oct 2021 06:07:18 GMT
    < Server: MToken/1.03
    < Content-Type: application/json
    <

    {
        "md5": "ede8216798c1649c79e70ac69f2f6e7a",
        "message": "Ok",
        "size": "20210",
        "tarball": "C20211009T090718.tkn",
        "token":"test"
    }

Format of the JSON response:

- `md5` is MD5 hash (checksum) of the tarball file [optional]
- `message` is a response message or text of error
- `size` is size of the tarball file, bytes [optioanal]
- `tarball` is the tarball file [optional]
- `token` is a token name [optional]

## GET /mtoken/<TOKEN_NAME>/<TARBALL_FILE.tkn>

This method performs getting (downloading) the tarball file (TARBALL_FILE.tkn) from repository of specified token (TOKEN_NAME)

    curl -v --insecure -o C20211009T090718.tkn \
      https://admin:admin@localhost:8642/mtoken/test/C20211009T090718.tkn

    > GET /mtoken/test/C20211009T090718.tkn HTTP/1.1
    > Host: localhost:8642
    > Authorization: Basic YWRtaW46YWRtaW4=
    > User-Agent: curl/7.68.0
    > Accept: */*
    >

    < HTTP/1.1 200 OK
    < ETag: "ce143b537c146024251dcd1a903205fb"
    < Accept-Ranges: bytes
    < Date: Sat, 09 Oct 2021 06:33:12 GMT
    < Server: MToken/1.03
    < Content-Type: application/octet-stream
    < Last-Modified: Sat, 09 Oct 2021 06:23:55 GMT
    < Content-Length: 20210
    <

    ... see C20211009T090718.tkn file ...

## DELETE /mtoken/<TOKEN_NAME>/<TARBALL_FILE.tkn>

This method performs deleting (revoke) the tarball file (TARBALL_FILE.tkn) from repository of specified token (TOKEN_NAME)

    curl -v --insecure -X DELETE \
      https://admin:admin@localhost:8642/mtoken/test/C20211009T090718.tkn

    > DELETE /mtoken/test/C20211009T090718.tkn HTTP/1.1
    > Host: localhost:8642
    > Authorization: Basic YWRtaW46YWRtaW4=
    > User-Agent: curl/7.68.0
    > Accept: */*
    >

    < HTTP/1.1 200 OK
    < Date: Sat, 09 Oct 2021 06:51:06 GMT
    < Content-Type: application/json
    < Server: MToken/1.03
    < Content-Length: 64
    <

    {
        "message": "Ok",
        "tarball": "C20211009T090718.tkn",
        "token": "test"
    }

Format of the JSON response:

- `message` is a response message or text of error
- `tarball` is the tarball file [optional]
- `token` is a token name [optional]