Inconsistent API definition (route <-> VoyagePlan)

[FCML-max]

Hi there,
we are also implementing a VIS server just like you are and came across an inconsistent Swagger API definition.

The swagger API defines a model for a VoyagePlan

For addition of new VoyagePlans the voyage_plan_controller provides the following method:

def upload_voyage_plan(voyagePlan, deliveryAckEndPoint=None, callbackEndpoint=None):
    """
    Upload VoyagePlan to VIS from other services i.e. Route Optimization service.
    :param voyagePlan: Voyage Plan in RTZ format
    :type voyagePlan: str
    :param deliveryAckEndPoint: Acknowledgement expected. Base URL for VIS as in Service Registry. An ack is send back to this url when the private application retrieve the message from the VIS 
    :type deliveryAckEndPoint: str
    :param callbackEndpoint: Callback expected. Base url of the vis instance as in the Service Registry. The callback response will be sended to the voyagePlans endPoint of the instance
    :type callbackEndpoint: str
    :rtype: None
    """
    uvid='parse:from:rtz'
    f = open('import/' + uvid + '.rtz', 'wb')
f.write(voyagePlan)
[...]

There are couple of issues here I'm concerned about which we might discuss:

The first parameter of upload_voyage_plan is called voyagePlan, that's why expect it to be a voyage plan as it is defined in the model package (see link above). However looking at the comments regarding the parameters it clearly states that this method expects a string. Furthermore it says that it wants a string in rtz format.

Since the actual route (attribute of model class VoyagePlan) is in rtz format I think the API designers thought of passing the route right to the upload_voyage_plan method. And as far as I can tell from the code that's also how you implemented it.

However, I think this is a misconception in the Swagger API because firstly there's a naming inconsistency (route != voyage_plan) and secondly it contradicts with the purpose of a Swagger model definition. I would usually define models which are serialized before sending and deserialized when receiving automatically. So in this case there should have been actual VoyagePlans be sent through the API instead of falling back to rather primitive data types (here string).

Can you please elaborate if you share our concerns or even have any background information?
Thanks in advance for your response

Best regards
Max

[karrika]

Yep. I found out that too. I had to modify the swagger file to have

consume: text/xml

The same was true for areas and text messages also.
So my swagger definition is different than the standard STM version because of this.

I fully agree with your reasoning. We could use json for all communication as it provides a consistent way to access the elements.

Parsing xml and evaluating payload schemas at run time is both error prone and tedious.

At this time I don't believe we could change anything anymore. The FAT has been done for all ECDIS manufacturers except Furuno. If we try to push VIS-2.3 out when everyone is supposed to go into production will get lots of negative votes.