Ontario’s new API Guidelines: How to create the building blocks of government on the internet
Editor’s Note: Jenny Zhang is a senior developer for the Ontario Digital Service. When she’s not building modern Javascript applications, she’s thinking about the impact of technology on society. Paul Vet is an open data and digital policy expert in the Ontario Digital Service, working to change the way the government builds digital services. Jenny and Paul coauthored Ontario’s alpha API Guidelines and this blog post.
You may not realize it yet, but you rely on APIs every day.
APIs — short for “Application Programming Interfaces” — are the interpreters that allow two completely different digital services or programs to talk to each other.
For example, there are lots of different weather apps available for smartphones. They all talk to weather APIs so they can show you an accurate daily forecast even if the app developers themselves know nothing about meteorology.
APIs aren’t just for apps on your phone
APIs also allow digital government services to talk to one another, to you as the end user, or to a third-party organization that might want to work with government data or functions.
Good APIs create an ecosystem of services that build on each other. Many online shopping websites connect to APIs provided by payment providers to allow you to check out using the service you prefer. Mapping apps often talk to several services simultaneously, including public APIs for traffic conditions and transit data, as well as private APIs that can find the best route between two endpoints.
Services that communicate well together allow tech teams to build and iterate more quickly, enable a more consistent end-user experience, and uncover unexpected new uses for products. When you work in the open and allow others to build on top of your efforts, there’s no telling what creative ideas developers might come up with. What’s not to like?
An API-first development mindset
At the Ontario Digital Service, we advocate for an API-first development mindset to accelerate how we design digital services. This means that we consider how our work might connect to other systems before we write a single line of code, and lay the groundwork for those future integrations from day one. We build towards a platform of complementary services, simplifying the user experience and making it possible to release exciting, real-time open data that can power research and business in Ontario.
Launching the new alpha API Guidelines
To help public servants in Ontario and other interested developers build great APIs, we’ve launched our alpha API Guidelines in English (et en français aussi à Lignes directrices sur les API).
The guidelines explain why you should build APIs, outline some of the business considerations (such as “eating your own dogfood”), show how APIs can help you follow the principles of Ontario’s Digital Service Standard, and give technical advice for how to implement good APIs that developers will love to use.
This should be more than a box-ticking exercise — these guidelines are meant to be a roadmap, not a roadblock.
We’re looking for feedback from the public, and from a variety of public servants working to improve digital services, including:
- executives or directors looking to deliver interoperable digital services
- software developers or systems architects looking for technical guidance
- product managers who want to learn more about API development best practices
- business analysts considering whether an API is a good solution for your problem
- policy advisors on a digital service looking to better understand how APIs can help fulfill policy goals
- content designers & experience designers who want to familiarize themselves with the principles outlined here so they can add their perspective
- data analysts generating insights from data using APIs
This isn’t the final version. We’ve posted the first draft on Github so that we can track all user feedback, and continue iterating.
Working in the Open
The draft guidelines are released under a Creative Commons 4.0 licence, which means you can borrow from and build on these guidelines for your own needs. That’s what we did! This document would not be possible without the great work that other digital governments have shared under similar licenses:
Stay in touch
We’d love to hear what you think. If you’re comfortable with GitHub, feel free to provide feedback as pull requests or issues.
You can also get in touch by email.
We’re also testing out a new notice to contributors about how we’ll use their contributions. Feel free to adapt this for your own needs as well!
And hey, if you used our guidelines to help you build something you’re proud of, we definitely want to hear about that, too. Happy building!
