I’m working on a personal project, a library that can access the weather forecasts and other weather related data from it.
However, a lot of the returned data is sometimes quite redundant or simply doesn’t make sense to have certain data within that particular XML element etc. Consider this XML data I get from the service, which contains the hourly forecast:
<hour>20</hour>
<hour_padded>20</hour_padded>
<min>00</min>
<min_unpadded>0</min_unpadded>
<sec>0</sec>
<year>2015</year>
<mon>3</mon>
<mon_padded>03</mon_padded>
<mon_abbrev>Mar</mon_abbrev>
<mday>21</mday>
<mday_padded>21</mday_padded>
<yday>79</yday>
<isdst>0</isdst>
<epoch>1426968000</epoch>
<pretty>8:00 PM GMT on March 21, 2015</pretty>
<civil>8:00 PM</civil>
<month_name>March</month_name>
<month_name_abbrev>Mar</month_name_abbrev>
<weekday_name>Saturday</weekday_name>
<weekday_name_night>Saturday Night</weekday_name_night>
<weekday_name_abbrev>Sat</weekday_name_abbrev>
<weekday_name_unlang>Saturday</weekday_name_unlang>
<weekday_name_night_unlang>Saturday Night</weekday_name_night_unlang>
<ampm>PM</ampm>
As you can see there is a lot of data that you probably don’t need, because you can calculate/convert the time/date information into a simple DateTime etc. Another useless series of fields is the “padded” ones. There a lot of other examples of this redundancy with other types of weather data as well.
So how should I approach this, have literally every field in the XML available to the user of the library, or just stick to having only the parts that make sense available to the user? I’m leaning towards only the parts that make sense, but wanted to ask the opinion of others.
1
I would follow the YAGNI principle and carefully think through what the client needs on his/her side.
Including things that you think the client is going to need is a symptom of a core problem – that being lack of research and/or knowledge what the client actually needs.
2
If the purpose of your API is just to provide data (which is true in my opinion),
then do not return redundant or formatted values.
In your example, returning single date/time is enough.
This makes your response more concise and less ambitious.
Making assumptions about consumer GUI and interpretation
of provided data is usually wrong approach, avoid.
Is your library a weather api that uses existing web services to get data?
In that case you should probably hide the details of the actual ws, and define your own set of attributes for weather data. That way you encapsulate the external dependency from the users of the api.
You may also want to watch how you get data from the xml. Try to only bind your code to the specific elements/tags you actually need. That gives you a bit of forward compatibility in case tags are added to the ws xml schema.
If you just serialise the whole xml to a class (ie add service reference), you create a much larger coupling.
As others have said, you should return only a single representation of each value. It’s just simpler and easier for everyone. How to format those values for display is up to the presentation logic, not the service logic. If formatting a dateTime value or padding an integer with zeros is too hard for the presentation logic to do on its own, something is seriously wrong with whatever framework/language the client is using for that logic.
But the other answers didn’t really address which representation to pick. So I wanted to add that you should pick a representation which:
- Contains all of the actual information. For instance, the month should be in there somewhere, but not ten different ways of specifying it.
- Uses the simpler/more concise representation when multiple options exist. For instance, if you use the 24-hour clock, you won’t need an AM/PM field. This is so trivial to add in clientside code that it’s simply not worth complicating your API.
- Is a structured object rather than a string. Otherwise all your clients have to write parsing utilities before they can start on the actual formatting. (Big exception for standard, widely-used formats like ISO 8601 which are exceptionally easy to parse and have many parsers already available. In fact, returning a single ISO 8601 string might be ideal for you.)
- Either avoids localization issues entirely or explicitly handles them. By that I mean, either the month/weekday/etc are represented by numbers/enums, or your service requests all have a language parameter so they can return properly localized strings. Whichever one you pick, be consistent.
Finally, if there is a legitimate reason for you to be doing the formatting in your service (eg, you’re generating a .pdf with a table containing three thousand dateTime values) then the client should be required to provide a format specifier in their request, and this needs to be very thoroughly documented. And the localization thing applies again.
You will probably want to expose it in an easily consumable format like a timestamp and let the consumer choose how to interpret it. Something else that might help is to assume that this is what your API returns and attempt to code to it in a couple different use cases. If it feels messy, try returning the data in a different format and see if it becomes easier to use.