This repository is a collaboration point to support the development of a common and fully-defined REST API to be implemented by EGC satellite service providers (currently Inmarsat and Iridium) and used by Maritime Safety Information (MSI) providers throughout the world.
The defacto standard for the definition of REST APIs is OpenAPI v3 which is a YAML or JSON document. The YAML and JSON representations are equivalent, this site uses YAML format for its readability advantages.
The OpenAPI v3 definition for the EGC API is openapi.yml. The abstraction of C-Codes is based on the International SafetyNet Service Manual, 2021, MSC.1/Circ.1364/Rev.2.
Documentation generated from openapi.yml is here (and is updated using this script).
Note that a number of design considerations are discussed in the opening description block of openapi.yml.
A useful tool for editing and visualizing the API in HTML documentation is at https://editor.swagger.io/.
Below is a visualization of the data model of an MSI broadcast (as a UML Class Diagram).
Notes:
- A SARBroadcast has zero or one SARBroadcastArea. When a SARBroadcastArea is not specified the whole coverage area is assumed.
- An MSI has zero or one Repetition. When a Repetition is not specified then the broadcast happens only once (there may still be the standard 6 minute echo).
- An EGC satellite service provider should be able to map this model to C-Codes if desired (raise an issue if this is not the case)
- An arrow in the diagram indicates a polymorphism relationship. In the above diagram, for instance, an MSI is either a SARBroadcast or a NonSARBroadcast. Travelling further down the diagram we see that a NonSARBroadcast is either a PiracyBroadcast, a NavBroadcast, or a MetBroadcast.
- A line (without arrow heads) indicates an association. For example, a MetBroadcast has 1 MetBroadcastArea (we say 1 to indicate that the MetBroadcast must have defined one and exactly one area to broadcast to). Traversing further and using our knowledge of the meaning of arrows we see that such an area must be either a Circle, Rectangle, CoastalWarningArea, or a MetArea.
Here are some examples of representing C-code sequences with json (Msi object):
2-1-13-10GA-11-00
{
"broadcast" : {
"navBroadcastArea" : {
"subjectIndicator" : "NAVIGATIONAL_WARNINGS",
"navAreaCode" : 10,
"coastalWarningAreaCode" : "G"
},
"priority" : "SAFETY"
},
"payload" : "hi there",
"echo" : true
}2-1-24-31S153E180-70-00
{
"broadcast" : {
"navBroadcastArea" : {
"lat" : -31.0,
"lon" : 153.0,
"radiusNm" : 180.0
},
"priority" : "SAFETY"
},
"startTime" : "2022-11-03T14:34:32Z",
"payload" : "hi there",
"echo" : false,
"repetition" : {
"number" : "TWICE",
"intervalHours" : 12
}
}2-2-34-06S146E02002-15-00
{
"broadcast" : {
"sarArea" : {
"minLat" : -6.0,
"leftLon" : 146.0,
"heightDegrees" : 2.0,
"widthDegrees" : 2.0
},
"serviceType" : "SAR_COORDINATION",
"priority" : "URGENCY"
},
"startTime" : "2022-11-03T14:34:32Z",
"payload" : "hi there",
"echo" : true,
"repetition" : {
"number" : "TILL_CANCELLED",
"intervalHours" : 6
}
}Here is the UML State diagram for an MSI (these states correspond to the values returned by a get status call in the OpenAPI definition):
The source for this diagram is in openapi.yml in the description field of the Status object.