This month, Sales is contributing to Angle of Attack in partnership with Engineering!
At FlightAware, a key uniting priority across both our engineering and commercial teams is ensuring our customers have every resource they need to succeed. In this blog post, I’ll detail how our teams provide accessible, reliable documentation to our users, whether you might be browsing our products, or actively working on integrating one of our APIs.
FlightAware’s APIs
For the purposes of this post, I’ll be focusing specifically on documentation for FlightAware’s suite of robust APIs, each designed to serve aviation data needs, including:
- AeroAPI – our modern query-based solution, providing customized access to users seeking both real-time and historical data for any application using a RESTful interface on a scale that is flexible and easy to integrate.
- Firehose – our streaming-based, enterprise grade solution, that delivers high-volume, real-time flight tracking data directly to customers via TCP socket in a JSON format, ideal for consuming large amount of data as quickly as possible.
Why Our Documentation is Pivotal
Availability of Documentation
Both of our APIs offer publicly facing documentation available to anyone online at FlightAware.com using the links below, no need to be a customer, and no log in is required:
We’re confident that providing well-maintained documentation that’s easily accessible helps users identify solutions to their needs independently – so we make it directly available! This also enables confirmation that FlightAware can provide the aviation data for a given use case at a customer’s leisure. Transparency and ease of access of our product information is a necessity from our perspective.
Enabling Easy & Timely Integration
For each of our respective APIs, FlightAware provides detailed guides and examples, helping developers quickly get up to speed with our products. This includes basic product information such as the available data types, to exact messages and available queries, as well as collections of sample applications to help users move faster to integrate.
AeroAPI and Firehose, while different in terms of data delivery, are designed to enable quick connectivity and data access. For example, AeroAPI allows for self-service access tiers that can be active immediately after sign-up. By providing detailed information in the documentation, you can prepare to integrate and being developing as quickly as you’d like.
Comprehensive Specifications
One of my favorite things to tell users about our documentation is that everything is available online, and that includes in depth technical specifications. Whether it’s all of the available queries in AeroAPI including the payload/response structure examples, or the commands available in Firehose once you establish a connection.
In both products the schema is provided using an open standard and that same schema powers our documentation. Firehose uses JSON Schema for all its possible messages, and this populates our message documentation. AeroAPI uses an OpenAPI (Swagger) spec file to power its documentation portal. In both cases this means product updates are documentation updates, and the schema files are freely available. Internally we use the very same schemas to validate any prospective changes to the interfaces so we can be confident what’s documented is the same as what’s delivered.
Applicable Examples
We’ve designed our pages to address most questions our broad range of users might have, but sometimes, an example is the most helpful thing to illustrate what our products are capable of. This is best reflected in our interactive documentation for AeroAPI, where using an AeroAPI key, you can make actual request via our UI and receive the same results you would get once you actually establish a connection to the API, not only enabling you to verify what query will work best for your use case, but also test how comprehensive our data sets are.
The Firehose Firestarter suite goes as far as to model a complete collection of services that acts as a template for quickly starting with Firehose data. Many concepts for how to maintain an ideal connection and process messages are presented as readable source code. It also functions as a template for architecting a formal solution in with preferred languages and tools. The goal is to provide as much of a turn-key experience as is reasonably possible.
Consistent Updates & Accuracy
Our APIs are constantly evolving, just look at AeroAPI’s Revision History (insert link). With that evolution, it’s critical that we update our documentation timely and accurately with every update, and prior to product releases, our team ensures that documentation will be updated accordingly. Online webpages and Documentation are always the first resource at FlightAware to contain the most recent information about each of our products, and we recommend it be your first line of defense for information pertaining to our APIs.
Tips for Success
- Check out AeroApps, our small collection of backend sample applications to help you get started with AeroAPI and Firestarter, our development accelerator that makes it easier than ever to integrate data from Firehose.
- Always review Revision History to ensure you’re leveraging all of our capabilities! By staying up to date with API enhancements, customers can continuously improve their applications and leverage new capabilities to stay competitive.
- Explore our Discussion Boards, and view Q&A regarding our APIs – you can even ask a question yourself! API Customers can even collaborate here or share advice from your experience with us.
- Review the FAQ for each API
Closing
In the future, we’ll continue to provide industry-leading resources for our customers. We believe that great API documentation is not a static asset, but rather a dynamic tool that grows alongside our consistently improving products and our customers’ needs. By continuously refining and expanding our documentation, we’re empowering users to innovate faster, operate more efficiently, and create compelling aviation solutions.
If you haven’t yet visited our Documentation Centers for each of our APIs yet, use the links below to discover how you may be able to leverage FlightAware data to power your next project or product!
