Favor empty array over error when retrieving departures

[marcelbuesing]

I think it would be better if the response would return an empty array. It's pretty messy to handle otherwise on the clientside.

{  
    "DepartureBoard":{  
        "noNamespaceSchemaLocation":"http://open-api.bahn.de/bin/rest.exe/v1.0/xsd?name=hafasRestDepartureBoard.xsd",
        "errorCode":"SQ002",
        "errorText":"There was no journey found for the requested board or time.",
        "$":""
    }
}

Suggestion:

{  
    "DepartureBoard":{  
        "noNamespaceSchemaLocation":"http://open-api.bahn.de/bin/rest.exe/v1.0/xsd?name=hafasRestDepartureBoard.xsd",
        "Departure": []
    }
}

[highsource]

Could you please give an example of URL which produced this error? I've managed to force SQ001 but not SQ002:

https://open-api.bahn.de/bin/rest.exe/arrivalBoard?authKey=<KEY>&lang=de&id=008000105&date=2015-12-11&time=00%3a00&format=json

Then, I'm not really sure if giving an empty list of departures is a good idea. This is an exception this should be masked as a normal data. An empty list of departures would mean "we have no departures at this station/date/time". But that's not the case. We may very well have departures but they may be out of the timetable period (like in the URL above). I think these are different situations which should be handled differently. OK, this shouln't be 200 response code but that's a different story.

[marcelbuesing]

Honestly I think it is perfectly valid to return an empty array in this case, there is nothing unexpected or exceptional here. Exceptionally would be an incorrectly formatted parameter (e.g. date), the id is incorrect or an internal server error occured... E.g. querying the Github API for a user that does not exist returns a list of empty users.

https://api.github.com/search/users?q=yzsfjdfjsd+repos:%3E42+followers:%3E1000

This looks to me like it will lead in many languages to code that looks like this:

try doRequest
catch
  if errorCode == SQ002 then everything is alright

Personally I am dying a little inside looking at that.

[highsource]

It is important to distinguish "no departures on this date" vs. "date outside of the supported timetable period" (SQ002). The first one is "we know there are no departures", the second is "we don't know if there are departures or not". Different animals so I won't use the same response for both.

This may be different for SQ001, I don't have an example of the query so can't judge.

[marcelbuesing]

Ok I get what you mean now. I guess in the case of being outside of the supported timetable period this is perfectly reasonable.