Federal Aviation Administration

Simple Tutorial

The beautiful thing about web services is that it doesn**t matter what technology you use as a consumer. Your code could be ColdFusion, Java, Python, Ruby, or virtually anything and our services still work the same. This is fantastic for interoperability, but also makes it very hard for us to give specific, relevant examples of how to consume our services.

What we can do is give a basic example of REST over HTTP that you can follow using nothing but your web browser. We'll also give one example of consuming a service in ColdFusion, the language on which this platform is built.

Brief Overview of REST

Our implementation of REST web services uses Hypertext Transfer Protocol (HTTP), which has existed since before the dawn of the Internet. Every time you type a URI or URL into your browser, you're sending an HTTP request for that resource, typically a web page.

And that's all it takes to consume our web services! Sending an HTTP request and then processing the results. In fact, we can try it now.

Making a Simple FAA REST Request

Follow this link in your web browser, preferrably in a new tab or window:

http://services.faa.gov/airport/status/IAD?format=xml

Whew, if you did it right you probably got a response back like this (this example is condensed):

So what happened? When you told your web browser to go that URI, the browser made an HTTP GET request to the resource. The server here figured out what you wanted and returned the response you saw.

Partial code examples of consuming REST services:

Understanding HTTP Methods

The "GET" in HTTP GET request is referred to as the method. There are various HTTP methods, but the common ones we'll be using for our web service requests are:

GET
Basic retrieval request for a resource or data. When you type a URI into your browser, you're sending a GET request.
POST
Submitting data to a resource and usually asking it to save the data. Most of the time when you're submitting a form on the web, your browser is sending a POST request.
DELETE
A request asking that a resource be deleted.
PUT
Asking the server to store or create the specified resource. For instance, uploading an image file.

It's important to understand that the method is of huge importance when consuming our web services. For instance, calling a URI referencing a user can achieve three different results depending upon the method used. GET would retrieve the user's information, POST would update the user's information, and DELETE would remove the user entirely.

Don't worry - in general most of our services are read-only and exclusively permit the GET method. If you pass a method in a request that's not supported by the operation, it'll throw back an error telling you exactly that.

When Things Go Wrong - Error Handling

So far our examples have all been working under the assumption that there were no errors encountered. Of course, we know that not to be the case in the real world.

For the purposes of the service framework, an error is defined as an unexpected behavior that occurred during the process of a request. It's important to note that what might be considered an "error" can often be an expected behavior.

For instance, a search operation returning no results (a blank object) and an HTTP status 200 OK code might be construed as an error, but in reality this is not outside the realm of expected normal operation.

So really when we say errors we mean bad things happen like a database server goes down or a required parameter wasn't passed to a URI. Ultimately it is the responsibility of your code to anticipate and appropiately handle errors. Our platform only makes you aware of them.

See the full list of HTTP status codes we employ for more information and an example error response.

This page can be viewed online at: http://services.faa.gov/docs/tutorial/