4

I am trying to learn something about how APIs work. I was told that DOL has the best API and supporting documentation in the federal government.

So here I am, on page 1 of the beginner's guide, and find this completely contradictory information:

Result Format

By default, the DOL V1 (api.dol.gov) API's responses are in XML format. To receive the data in JSON, send an "Accept" header with "application/json."

Result Format

Data.dol.gov sends responses by default in JSON format. To customize the return format, simply add /format/xml or /format/json to the request URL.

What on earth is going on here?

philshem
  • 17,647
  • 7
  • 68
  • 170
Rick Jones
  • 41
  • 1
  • Thank you for your feedback. People sharing their joys and frustrations are what allow us to make our documentation better. Apparently, our documentation can use some work. If you're comfortable doing so, please click the "Report Bugs" link at the top of our developer portal and share with us the things about our documentation that confuse you, frustrate you, or you even like. We do take feedback we receive seriously because we want to make our tools better. Also, feel free to look at our SDKs and sample code on the site. – Mike Pulsifer Aug 01 '16 at 12:43

1 Answers1

3

When you connect to an API, you are simply creating long URLs that contain filters, flags and other parameters. So you can test your URL in the browser before using a programming language.

In this case, the API documentation is saying that if you provide no format parameter, the default response will be XML. But, if you prefer JSON, you can add a custom parameter that will return a JSON response. And if you prefer to be explicit, or toggle between XML and JSON, then you can explicity request XML, even though it is the default.

Every API (web service) has a different structure, but here's an example of 3 web service requests that return the same data but in different formats

https://www.quandl.com/api/v3/datasets/WIKI/AAPL.json

https://www.quandl.com/api/v3/datasets/WIKI/AAPL.csv

https://www.quandl.com/api/v3/datasets/WIKI/AAPL.xml

That being said, technical documentation is written by technical people, and it may be tough to get started with the technical documentation for a web service. For the types of APIs you are interested in, you may want to read some info that's not specific to a certain tool. For example, REST servers - Applied to web services

philshem
  • 17,647
  • 7
  • 68
  • 170