ARCLOS - Amateur Radio Communications LOgging System

文末の括弧内に示した助動詞はRFC2119に準拠する。文書内では大文字と小文字は区別する。

概要/設計思想

• zLog/zServerの代替的なもの
• ネットワークの安定性は信用しない(SSHやTelnetの常時接続は切断されるとだるいから使用せず、TCP/UDPを利用した規格で逐次通信する)
• マルチオペレーションを想定して、複数のクライアント端末からネットワーク経由でサーバーに交信履歴を送信(登録/REGISTER)
  • まあlocalhostで立てて個人でも使えるしね
• ログ検索(SEARCH)用のAPIも提供
• 現時点までの他端末から登録されたログを返却(RETURN)する
• 返却のみを求める(GET)APIも提供する
• 通信プロトコルにはHTTP(POST) REST APIを使用。

語彙

• 登録(REGISTER): サーバーにログを送信すること
• 検索(SEARCH): ログを検索すること
• 取得(GET): クライアント側から、クライアント側のログを更新するためにクライアントが持っていないログをを求めること。
• 編集(EDIT): 登録したQSOを編集して修正すること

構成

全体

• REGISTER、SEARCH、GET、EDITに対応するエンドポイントにリクエストを送信
• HTTPを使用したREST APIによる通信を基本とする

サーバー

• JARL形式のSSV(Space-Separated Value)もしくはTSV(Tab-Separated Value)形式のテキストファイルでログが保存されることが容易であるためそれを行うサーバーも実装可能である(MAY) 面倒
  • 試してないけど多分CSVみたいにExcelで開ける
• ログの重複をサーバー自身で検知した場合の挙動はサーバーに依存する
• 備考欄を除いて大文字の使用が推奨される。大文字と小文字はの区別はしないことを推奨(SHOULD)
• 日本語などのマルチバイト文字などASCII以外の文字は使用してはならない(MUST)

クライアント

• 一度の登録で一つのエンドポイントに対して登録(MUST)
• ログ検索をする際、SEARCH要求を行って毎度サーバーから検索することも可能だし、GETでpollしてクライアントのローカルに保存されているログから検索してもよい。どちらを採用するかは実装に依存する
• 備考欄を除いて大文字の使用が推奨(SHOULD)
• 日本語などのマルチバイト文字などASCII以外の文字は使用してはならない(MUST)

API仕様

クライアントは以下の値をサーバーに送信

• REGISTERの場合

  • [optional] id: string : 交信時刻をYYYY-MM-DDTHH:mm:ss.sssZで表したもの。サーバ実装によってはサーバ側で時間を付けるため解釈されない場合がある
  • band: string : 周波数帯。MHz単位が望ましい。(SHOULD) 単位不要
  • mode: string : 変調方式。SSBの場合はUSBやLSBと書いてもSSBと書いてもよいが統一すること
  • call: string : 交信先のコールサイン
  • rrst: string : 受信したRSTコード
  • srst: string : 送信したRSTコード
  • hisnumber: string : 送信したコンテストナンバーのうちRSTを除いた部分(存在しない場合は任意の値、存在しなくても省略不可
  • mynumber: string : 受信したコンテストナンバーのうちRSTを除いた部分(存在しない場合は任意の値、存在しなくても省略不可
  • pts: int : 得点
  • [optional] operator/memo: string : 備考

• SEARCHの場合

  • query: string : 検索するコールサインの一部または全部

• GETの場合

  • id: int : 最後に取得したログのID(=時間)。

• EDITの場合

  • id: int: 編集対象のQSOのID(=時間)。

port: 6465: HTTP(POST)によるエンドポイント

基本的には上記の情報をJSON形式で送信。HTTPSの対応や認証等はサーバに依存

通信データ形式は以下の通り

Accept: appilcation/jsonとContent-Type: appilcation/jsonは必ず指定すること

qso型として以下の形式を指定しておく

{ 
    "id": id,
    "band": band,
    "mode": mode,
    "call": call,
    "rrst": rrst,
    "srst": srst,
    "memo": memo,
    "contest_specifics": {
        "hisnumber": hisnumber,
        "mynumber": mynumber,
        "pts": pts
    }
 }

また、operator/memoのキー値がmemoであることに注意。備考がない場合は長さ0の文字列とする。

/register

request

HTTP POSTで、payloadは以下

{
    "qso": qso
}

具体的には、

{ 
    "qso": {
        "id": "2024-07-21T21:36:46.358+09:00",
        "band": "3.5",
        "mode": "FM",
        "call": "JA1YXP",
        "rrst": "59",
        "srst": "59",
        "memo": "memo",
        "contest_specifics": {
            "hisnumber": "13M",
            "mynumber": "10M",
            "pts": 1
        }
    }
 }

response

{
    "status": true,
    "qso": { 
        "id": "2024-07-21T21:36:46.358+09:00",
        "band": "3.5",
        "mode": "FM",
        "call": "JA1YXP",
        "rrst": "59",
        "srst": "59",
        "memo": "memo",
        "contest_specifics": {
            "hisnumber": "13M",
            "mynumber": "10M",
            "pts": 1
        }
    }
}

/search

request

HTTP POST, payloadは以下

{
    "query": query
}

response

{
    "status": true,
    "results": [
        qso,
        qso,
        ...
    ]
}

/get

request

HTTP POST, payloadは以下

{
    "id": id
}

response

{
    "status": true,
    "logs": [
        qso,
        qso,
        ...
    ]
}

/edit

request

HTTP POST

{
    "id": id, //timeはQSO固有の値であるためこれで特定のQSOを識別する
    "qso": 修正後のqso
}

response

    "status": true,
    "qso": { 
        "id": "2024-07-21T21:36:46.358+09:00",
        "band": "3.5",
        "mode": "FM",
        "call": "JA1YXP",
        "rrst": "59",
        "srst": "59",
        "memo": "memo",
        "contest_specifics": {
            "hisnumber": "13M",
            "mynumber": "10M",
            "pts": 1
        }
    }
}

エラー

サーバーで何かしらのエラーが発生した場合はstatusをfalseにしたうえでmsgキーに内容を記載して返却