ACARS Protocol

This is the standard WebSocket protocol for Naru ACARS software.

Concept

Every request presented below follows the common JSON format.

{
    "intent": INTENT,
    "ident": IDENT,
    "bulk": BULK
}

Attribute	Type	Definition
INTENT	Text	Some text which designates the request type
IDENT	Text	Any text which persists in the message sent back from the server
BULK	Object	Body of the request

Authentication

Plain API Key must be presented once the connection is established.

Otherwise, any further messages will be rejected by the server.

Request form:

{
    "intent": "auth",
    "ident": "1",
    "bulk": {
        "key": "your-api-key"
    }
}

Possible response:

status	message	response	remarks
200	Success
400	Bad Request	Request form is invalid.
403	Forbidden	Key already in use.
404	Not Found	Key does not match.
500	Server Error

Fetching data

You may request to fetch information about the pilot.

Latest flight booking

Request form:

{
    "intent": "fetch",
    "ident": "2",
    "bulk": {
        "type": "booking"
    }
}

Possible response:

{
    "intent": "response",
    "ident": "2",
    "status": "200",
    "message": "Success"
    "response": {
        "flightplan": {
            "callsign": "NA123",
            "aircraft": "A320",
            "origin": "RKPC",
            "alternate": "RKPK",
            "destination": "RKSS",
            "off_block": "2023-07-30T04:50:00Z",
            "on_block": "2023-07-30T06:00:00Z",
            "route": "DCT OLMEN OLME2T",
            "remarks": ""
        }
    }
}

status	message	response	remarks
200	Success	JSON	Booking data is parsed to JSON.
404	Not Found	You haven't booked a flight.
500	Server Error

Start a new flight

Charter flight

Pilots may conduct a flight without booking a flight schedule.

This request shall be used to start a charter flight.

{
    "intent": "start",
    "ident": "2",
    "bulk": {
        "scheduled": "false",
        "flightplan": {
            "callsign": "NA123",
            "aircraft": "A320",
            "origin": "RKPC",
            "alternate": "RKPK",
            "destination": "RKSS",
            "off_block": "2023-07-30T04:50:00Z",
            "on_block": "2023-07-30T06:00:00Z",
            "route": "DCT OLMEN OLME2T",
            "remarks": ""
        }
    }
}

Possible response:

status	message	response	remarks
200	Success	New flight is submitted.
400	Bad request		Request form is either incomplete or invalid.
401	Bad callsign		Callsign is either invalid or in use.
450	Bad state	The flight has already started.
500	Server Error

Scheduled flight

This request is used to start a flight with the latest booked schedule.

The bulk.flightplan object presents what data should be replaced from the original plan.

The server will respond with an error if it's unable to find a schedule that starts within an hour.

{
    "intent": "start",
    "ident": "2",
    "bulk": {
        "scheduled": "true",
        "flightplan": {
            "alternate": "RKPC",
            "route": "KAMI1W KAMIT Y722 OLMEN OLME2T"
        }
    }
}

Possible response:

status	message	response
200	Success	New flight is submitted.
400	Bad Request	Request form is either incomplete or invalid.
404	Not found	The pilot has not booked a flight.
440	Before flight	Unix timestamp
450	Bad state	The flight has already started.
500	Server Error

Cancel flight

This request is used to suspend the current flight.

{
    "intent": "cancel",
    "ident": "2",
}

Possible response:

status	message	response
200	Success	Flight is cancelled.
450	Bad state	There is no flight.
500	Server error	Internal error.

Status report

ident attribute is not required here since the server won't reply back to this message

The aircraft status should be reported every less than a minute.

Failing to comply may result in a flight cancellation. The correct format is as follows.

{
    "intent": "report",
    "bulk": {
        "latitude": "37.46",
        "longitude": "126.44",
        "altitude": "23",
        "ias": "0",
        "heading": "335"
    }
}

Event report

ident attribute is not required here since the server won't reply back to this message

The flight event should be reported thoroughly.

Status change

{
    "intent": "event",
    "bulk": {
        "event": "status",
        "status": "1"
    }
}

Divert to another airport

{
    "intent": "event",
    "bulk": {
        "event": "divert",
        "airport": "RKPK"
    }
}