This is an example of a slightly more involved JSON object. This chunk of data, for what to expect for several future date’s weather, is “structured data” that is passed from a source (like the National Weather Service) to recipients like you and me when we want to check on the weather forecast (for more than just one day) from our cell phone.
In this object there is specified a particular location by longitude and latitude coordinates, and the range of days for the forecast is an array (or list) of dates and the forecast for each. Here’s the corresponding documentation:
A new endeavor is writing API documentation. This may sound daunting, but after a short introductory online course I find it to be only moderately challenging. First, what is API? This is an acronym for “Application Programming Interface,” and what an API does is exchange data between a device (like a cell phone or a laptop) and a server. For example we all have apps on our smartphones these days and the display of today’s weather forecast may well be handled by an API, and it might look something like this:
This is an example of a JSON object (there are two types, JSON and XML), or Java Script Object Notation (and XML is the acronym for eXtensible Markup Language). This chunk of data, for what to expect of tomorrow’s weather, is “structured data” that is passed from a source (like the National Weather Service) to recipients like you and me when we want to check on the weather forecast from our cell phone.
The documentation part is what is in high demand these days. Documentation is needed so that software developers who want to create usefull apps can search for and implement thousands upon thousands of existing API’s that currently exist either in public places (like free software projects) and even private places (like within a corporate private network).
So here’s how I would document the example JSON API above:
The date of the forecast
Format is YYYY-MM-DD
The type of weather expected
May only have these values: “sunny”, “overcast”, “partly cloudy”, “raining”, and “snowing”
Maximum temperature on forecast date
in degrees Celsius
Minimum temperature on forecast date
in degrees Celsius
in km per hour, kph
Flag if conditions are expected to be dangerous
True if conditions are expected to be dangerous, otherwise false