Choose API design principles

 

Understand APIs, the API gateway, and the major steps to build a strong API. Please note this is a work in progress. We’ll gradually expand the detail and topic coverage.

Before you begin

It’s well beyond the scope of this document to explain exactly how to build an API. However, what this how-to guide can help you with is where to find best practice design principles to guide you or your vendor’s API development work.

Note: Keep in mind the WoVG’s approach to APIs will change when the WoVG API gateway becomes available.

What is an API?

An Application Programming Interface (API) in simple terms, is a translator or bridge. It allows two pieces of software to work with each other (for example, an enrolment payment form and a personal bank account) — even though they were never originally designed to share information with each other.

Governments have started to look at ways to share information. This means government will adopt the current trend, which is to use Web APIs to support sharing content and data, between communities and applications.

The more technical way to describe an API is ’a standardised service based on a common protocol (rules for how the service works) and formats (schema for using the service) familiar to developers. At their most basic, APIs combine protocol (the means of interacting with data and services) and format (the model by which the data and services are arranged in order to allow such interaction.)’

What does the Victorian Government recommend?

Where possible, include an API with every Victorian Government online service.

Build an understanding of Enterprise Victoria's WoVG Information Management Framework.

What standards must be met

This How-to guide is a research and decision-making tool, so we haven't mentioned specific mandatory standards. Industry protocols, such as SOAP (see Glossary below), should guide your thinking and planning.

 

Why APIs are important

Share data

Providing information and services through Web APIs supports interoperability and openness. Well-designed APIs make data freely available for use within agencies, between agencies, in the private sector, or for use by citizens.

Increase reach

Increase the reach of your services by allowing other agencies, partners, and the private sector to integrate – and amplify – your agency’s data, transactions and content.

Save time through automation

You can update data or content once, and your API can refresh in multiple locations automatically on a website, mobile platforms, and on social media platforms.

Save money

Save on costs by allowing third-party innovators to create new, useful products and services beyond the scope – or budget – of your agency. 

Speed up product development

Speed product development through improved prototyping and ease of access for internal teams and sister agencies by allowing granular and open access to content.

Build markets

Build markets by improving entrepreneurs' access to government resources like:

  • transport
  • health
  • the economy
  • energy
  • education
  • the environment

Empower citizens

By opening access to government information and services, we make it possible for third-party developers to build their own versions of online government services.

Understanding the applications of APIs

To understand the applications of APIs it’s helpful to look at three examples now used in Victoria.

PTV

The PTV Timetable API provides direct access to Public Transport Victoria’s public transport timetable data.

VicRoads

VicRoads Bluetooth sites contain sites where BlueTooth detector equipment has been installed to detect vehicles emitting a BlueTooth signal (that is, a BlueTooth device is turned on).

Data.vic

The open data directory www.data.vic.gov.au CKAN platform provides a number of data sources available through the CKAN API. One example is being able to find Victorian liquor licences by location.

The Victorian Government API gateway

The Whole of Victorian Government API Gateway provides a centralised access point for APIs being published by Victorian government agencies.

The API Gateway’s benefits include:

  • single access point to government APIs, and fewer peer-to-peer connections
  • WoVG standardised APIs
  • consistent API documentation
  • authentication and access control
  • controlling and prioritising access
  • performance assurance, measurement and reporting
  • data orchestration and experience APIs

The API Gateway team  will have the capability to assist agencies with technical services including:

  • development and hosting of API’s
  • API product strategy, API architecture and API design support
  • API quality assessments

For more information or to get connected to the Gateway contact apiteam@dpc.vic.gov.au

Best practice design principles for APIs

We think this US Government site, 18F, offers today’s best guide to API design principles. 18F is an office inside the US government General Services Administration's Technology Transformation Service. It helps other federal agencies build, buy, and share digital services.

Use these to help guide how you specify your development needs or your own development efforts:

We also highly recommend:

How to build an API in five steps: high-level summary

This list, therefore outlines the major decision points for a WoVG API, keeping in mind the way we go about building API’s is about to change radically when the WoVG API gateway becomes available in 2017.

Step 1: check what's being built or is planned

Check with your agency’s IT Manager to find out if there are any developments in place, or in progress, that can help make your API available. (For example, your department might have an API management platform that will make distributing your API easier.) Also, check to see if your department can build the API for you.

Step 2: make sure it's best practice and complies

Whether you’re building a new API yourself, with the help of your department, or engaging a vendor to supply a new API, make sure it complies with industry best practice and complies with Victorian Government Digital Standards (including security and privacy). Refer to the Australian Government Digital Transformation Office API Design Guide for practical, comprehensive advice about building APIs.

Use the currently preferred protocols: that is REST protocol when possible, in preference to the deprecated SOAP (see Glossary). With the upcoming API Strategy we expect to see more practical, hands-on guidance on how to build APIs.

Step 3: Document your API

Document your API. How well you do this can make or break your developer community’s  acceptance. See RESTful Description Languages.

Step 4: Publish it

Publish your public APIs on data.vic.gov.au and contact the API Gateway team at apiteam@dpc.vic.gov.au to make your API discoverable.

Step 5: Enforce API governance gently

If you are involved in governance, enforce governance gently. Being heavy-handed with governance will mean APIs have a hard time getting built.

Glossary

API

Application Programming Interface.

REST

Representational State Transfer: a protocol for machine to machine communication - now the preferred industry protocol.

SOAP

Simple Object Access Protocol: also a protocol for machine to machine communication.

RESTful API Description Languages (including Swagger (formerly OpenAPI), RAML, WADL, WSDL). The above are formal languages designed to provide a structured description (that is, documentation) of a RESTful Web API useful to both human and automated machine processing.

Related How-to guides

How to publish a government open-data set

How to manage security

Other good reads and resources

The Digital Transformation Agency's guide to using existing research and data.

Join the conversation on digital

Get advice and share your insights about this topic with other digital practitioners on the WoVG Digital Group on Yammer (VPS access only).

Can’t access Yammer? Contact us by email: contact@dpc.vic.gov.au. (We may post your comment on Yammer for general discussion. Please tell us if that’s not OK.)

 

Back to top