Skip to main content


As part of a regular Emerging Technology series the Service Integration team at the Department of Internal Affairs (DIA) brought together presenters from inside and outside of government to share how they were using Application Programming Interfaces (APIs) for service delivery and ways we could improve service delivery with other approaches.

APIs are a set of clearly defined methods of communication between various software components. They are not an emerging technology as they have been in use for decades. What is interesting now is how government is thinking about APIs for service delivery, including how open government APIs can be used to deliver innovative services by third parties, and by businesses to directly transact with government.

Good API development and management practices based on common standards are essential for robust API-driven service delivery. This includes ensuring you have an experience API layer (in addition to system and process APIs), and are designing APIs that are empathetic to the way developers will want to use them (DX). (Also see the blog post on API security). However, two of our presenters challenge us to think beyond APIs, and how we should learn from the mistakes of the past and consider moving from location and content-centric to people-centric models of data flow.

In addition to the presentations here, another recent example of API use is the reimagining of the Family Services Directory as an open API that SmartStart is now using for its location based service directory. See the blog post on the first use case of this reusable component.

If you’re interested in finding out more about emerging technologies at our regular showcase then please sign up to our mailing list. We encourage you to also view the presentations from our previous Emerging Tech sessions.

Government API strategy and standard

James Collier from the Government Chief Digital Office (GCDO) in DIA talks about the Government API standard. The standard points towards a digital government strategy where APIs have a critical role in government digital transformation. A new version of the standard will be released within the next few months.

For a more accessible video experience, request the YouTube HTML5 video player

> Transcript of James Collier's presentation on the Government API Standard

We are about to embark on version 1.1 of the API standard for government. I don't know whether many of you have seen the existing government API standard, which is on

Middleware New Zealand helped us together with a group of agencies in about 2016 to develop that. So we've had about 18 months or so of use with that standard. And since then, obviously, we've learned a little, both from people using the standard, but also in terms of the evolution of the government digital strategy.

So for those of you who aren't familiar with the document, it's in two parts. There's a business section, section A, which is about why agencies would want to adopt APIs, what they need to look for in APIs in order to achieve their business goals, and a technical section, which is part B.

So a few points on motivation for a digital strategy in government. Obviously, the changes that have been wrought in the private sector through digital transformation have been forced by competition, in many cases. People whose businesses are ripe for digital transformation have had to adapt or go the way of the dinosaur.

Government doesn't have that pressure to quite the same extent. However, it still has pressure from its voters. It still has pressure to deliver the best public services at the best price. And we contend, as part of our digital strategy, and have done for the last four or five years, that an API strategy is critical to achieving that digital transformation.

And that API strategy needs to be visible right within the business. Digital strategy is not an ICT strategy with a new name. It's actually a change to the way you do business. It's change that implies a change to your operating models and the way you interact with your customers and your intermediaries.

And although there has been that section A in the API strategy articulating some of those themes, it's something that we in the GCDO, Government Chief Digital Officer's business unit, is that we need to make that more visible. And we need to have this embedded right throughout organisations, with expertise from executive right through to greater understanding down at technical levels within government agencies.

Our experience with the API standard to date, version 1.0, it has generally been well received. And I was pleased to see quite a few here are actually aware of the thing and have used it.

As I just said, section A, the business section, has been very well received by those who've read it. But it's probably not in a place where the audience for it will necessarily find it. Senior people don't necessarily go looking for standards first. We will, therefore, be bringing some of that material straight onto the site.

The other things that have been noted from use of the standard, there's a lot in there around authentication and authorization, and how you achieve that through the APIs that agencies are putting forward, where authentication, authorization is needed. But there is a lack of infrastructure to drive that. You actually need digital identity that is consumable through OAuth and the like, in order for that part of the standard to be readable, usable, and applicable.

The other thing that we've sort of learned is that we need to treat API developers as customers. How many of you are from the private sector or from the supply sector, developing standards for government? Yeah.

Well, I think the message is that government APIs need to be developed in such a way that the consumers are seen as customers, and not just as tech bodies that need to put up with whatever they're given. They need to be involved in co-design. And we need to be understanding and listening, which I will do very shortly, to the voices of those who are using them.

And one very specific point that was raised was around the use of API keys. The original standard said, for example, always use them so you know who your customers are. Well, if there's a reason to do that, by all means. We won't make it mandatory though, in the next version. And we should at least make keys trivial to obtain, so that we get the best experimental use of the APIs that are put out there.

So that's all I have to say. We are engaged, and I hope to have another release of the standard within the next few months. We will be working probably on having material that is living, sitting around the standard. We hope to have a web environment where we can make continuous guidance around the standard, rather than have it just delivered once every two years and updated and put in PDF form.

API driven government service delivery

Ting Sun from the National Library of New Zealand (DIA) talks about the Digital NZ API and how people are using it to find, share and reuse over 30 million pieces of digital content related to New Zealand.

> Transcript of Ting Sun's presentation on the Digital NZ API

[I am from] Digital New Zealand, which is part of the National Library and part of the Department of Internal Affairs. I just want to know if anybody have already used or heard of Digital New Zealand before. Good, good, good, love those hands. So for the ones that hasn't raised their hands, I just want to tell you what we do, quickly.

So Digital New Zealand is an aggregator for metadata of digital content that has anything to do with New Zealand. It's nationally or internationally. So we all bring them in. And so currently, we have over 30 million digital content as searchable on DigitalNZ that is provided by our wonderful 200-plus content partners. Without them, we are nothing.

So the key of-- I'm sorry, the goal of what we do is, we make sure we make all of those 30 million content easy to find, share and reuse by anyone in the world. And we do this by providing it through our website, as well as our API.

So with our API, many organisations can use our API to build things that is just for their use. So National Library website and papers past, as well as NZ Research, they have their specific filters set up to bring up the content that they want to present. So is Seismic. All they needed was to create this front end. And all the back end is powered by Digital New Zealand. They saved a lot of trouble, resources, and headache. And we take on their headache. We were like, no problem.


At DigitalNZ, we call our API "the magic hat," because it is small. It is simple. It's light. But between the content we have and to spit out all the content for people-- for the API-- for the developers to use, without API, we can't really do this in this nice, beautiful way.

So this is the web browser version of our API. I feel like this is a bit redundant in this environment, because everybody here is so intelligent. And I am the least technical person here, because I have just started my API journey. But I'm still very proud of [CHUCKLES] explaining how to make an API call on DigitalNZ.

So it is actually really simple to get a key to access our API. So you just go into DigitalNZ and sign up. You will get a standard key. But if you want to make larger calls, no problem. Just let me know or let anybody from the team know. We will increase your call volume.

So the view here is in JSON view. But you can always look at XML or RSS, whichever one you prefer. And you can find all the detailed documents on the DigitalNZ website, just down there. It's really handy to help you to construct the API calls if you are a beginner like me, which I found is like the Holy Bible when I try to use our API.

Here, just a quick example of me trying to find dog-related content for-- because it's 2018, the Year of Dog.


And you need to sometimes promote this. And just out of curiosity, sometimes, I wanted to find out which of our content partners has most dogs. So I like them more sometimes.


And so just by looking at our API-- this is boring, but I am a very visual person. So we have this lovely API user called Monique. And she created this Culture Collage. And then anything you want to search on DigitalNZ that has an image, it will just present the images only.

As she said, that rather than a technical advanced search and using a lot of filters in the expressions, modifiers, and then result a list, she feels it's much more fun to just reduce information clutter and watch a river of image go by, which I thought was really beautiful and also satisfying just to see hundreds and thousands of dogs.


Love it.

But we also have great use-- on the ground floor of the National Library, you can see this real liveline table. And feel free to use it. And this is also powered by our API. So all the metadata we have is presented here. This table, you can only found the National Library host content. So you can have a look. Do your search, maybe when you're born and bring the memory back, when you-- those things, the streets that you used to walk on.

And I don't know if you have heard of NZMuseums. They also use DigitalNZ API as a plug-in down this side. So when you search for something on NZMuseums, this side panel also brings you the results on DigitalNZ, so you can go further with your discovery. Can I just stay on this slide? No. [CHUCKLES]


And that same creator of Culture Collage has also developing this. I've asked her if I could show it. This is not available yet. But I just found it so amazing. She has provided-- she has built this plug-in for Google Docs and Google Slides. So when you are writing your research or you want to create your presentation, and you want to insert images that can be found through DigitalNZ, as well as other museums-- she has included other museums, also DPLA or Trove-- this plug-in gives you the option. And you can just highlight the words. And then you can search for relevant content straight away. And then you can insert with the metadata, as well as the rights and restrictions showing.

OK, here, I promised fun, right?


And so this is the funnest thing I could think of. So my colleague has created this. It's not live, but we would just play with it. He just grouped content on DigitalNZ by searching "head, body, and leg." And it would just, every time, generate a mixed person or a creature by the content that surfaced on DigitalNZ. That is all I have. And do you have any questions?

Ross Park from the Ministry for Business, Innovation and Employment (MBIE) talks about the development of a digital strategy for Immigration New Zealand and the future role of APIs to enable third party service delivery.

> Transcript of Ross Park's presentation on the digital strategy for Immigration NZ

I work for Immigration, and we're in the process of quite a large transformation. And underpinning it is this desire to describe and articulate what this whole "digital" thing going on-- have you all heard of the digital revolution? The fourth revolution, it's coming!


And like a lot of government agencies, we're pouring money into technology. And we've got an API strategy. Some guy wrote an API strategy for us. We thought, that's brilliant. But we don't have any real context of what this is all about. And was that a good $10 million that we spent on quite a chunky, expensive IT solution? So they came and asked me-- OK, that's really weird. [CHUCKLES]

[Person off cameras says, "Oh, OK. We can try a different format and start again if you want."]

No, that's all right. I'll just talk to it

To look at describing or articulating a business strategy. They had our IT architects do it, and it was all about a technology roadmap. And we looked at digital and said, digital is very little about technology. The technology is just the enabler. Digital is about reinventing yourself as a business.

And APIs do play a part in that. And there's two components. There's the customer expectations that we've got. And we know that the customers out there, they want more. It's pretty simple.

We've got some technology enablers that are coming. API is one of them. AI is another one that's kind of I think being oversold right now. It's a little bit down the track there. It's still incredibly expensive. And like a lot of these things, right now, you just can't get people who can programme AI. So it's for the big people now. It hasn't gone down as a commodity for us.

But these are the two. And there's a nice little thing connecting them together. When you put the customers with technology together, you're starting to talk about being a digital business, linking those two, ensuring we're delivering what we need to the customer and we're effective in using technology. So this is about the journey that we're looking at, that we got asked to describe. How does all this fit together? And are we even doing the right thing?

So we sit together to do a digital strategy. And we're at the final stages of doing that. It's been really quite interesting. We've worked with quite a lot of the other government agencies. We're the first of the camp that said, actually, we need to have a strategy for this stuff. We cannot be spending $10 million, $15 million on massive IT projects where we don't have any goal of where we're going. That's just not a good place to be.

So we said, we want to have a vision. We had to stretch ourselves and look out a little into the future, and go, "What is the world going to be like for somebody who wants to come to New Zealand, who has to get a visa?" Right now, they have to do it on paper. Very shortly, they'll be able and they'll be mandated-- for most of them, they'll be doing it on a web form.

But we said, but that's not the future. In the future, I would expect that I'll just go to a booking agency and go, "Like to go for a holiday to New Zealand, thanks". Hit the button, and I get my visa. Because if I'm a good person, it should just go to straight through. This is the expectation we have.

And trying to explain not only that's the end picture we're going to, but how do we actually get there to the business in a way that they could understand was a little bit of a challenge. We came up with the idea of digital horizons. And they're a little bit conceptual. But they kind of work, and they allow business people to understand what we're talking about.

And they are-- we called them the digitising. We called them the connecting. And then we called it integrating. And they're three separate stages that any capability that we want to end up moving to the digital world, they go through all of those three stages. Well, most of them do.

I think I'm stuck here, am I?

OK. So we ended up having lots of people who spent a lot of time analysing customer insights and what the customer needs. I actually boil it down, in terms of digital, to some pretty clear things. They actually want a choice of where they do business. They don't want to have to come into offices. They may want to do it down at the pub, while they're out on the beach. It's their decision. They want to make those choices.

They also want to choose when they do their business with us. Oh, OK, it was up there. [CHUCKLES] This is really moved around. They also want to choose the channels that they do their business from. They may be happy to be using a web form. They may want to do mobile apps. But mobile apps aren't the future. I think-- who thinks mobile apps are going to be the future for us? I think they're just a stepping stone to what's going to happen next.

And they're pretty demanding. They're a lot smarter. So trying to actually meet the customer needs-- everybody talks about improving customer experiences. It's really interesting. We need-- this is the problem that as an organisation we're going to-- how do we deliver all that?

How do we produce that for the customer? Because we've got a change of government. And we don't have any money anymore. They're not spending money on Immigration, they're spending it somewhere else. So we're living in quite a financially constrained period of growth. But we've still got to keep growing. I've gone the wrong way, haven't I?

So the end game for us is not about devices such as iPhones and that. It's actually more about a level above that, which is the idea of these ecosystems are starting to be developed. So that's simply becoming a channel to the ecosystem. China, they're huge, where they'll do banking, they do networking, entertainment. They all do it on a single platform. And what people are doing is plugging into that platform and providing services that they can consume on that platform.

And we go, isn't that the kind of world that as a service provider producing visas we actually want to start moving towards? So if I apply for a job, why shouldn't I just get the visa at that point? Or I want to come for a holiday, when I book my ticket. And should we not be able to do that anywhere?

As long as we've got things secure on our side of stuff, we basically control the rules for processing and making the decisions and the information. If you give that to us, it's our job to come up and go yes or no? I think we can do that internally. What's wrong with us pushing that out?

And it was real interesting. When we started talking to our management about that, first was talk to the hand. Talk to the hand. Didn't want a bar of it. But we started telling these stories and explaining to people. And eventually, we're starting to hear the conversations are changing now. They're going, yeah, we're looking now at partnering with third parties and starting to move out a little bit in our trust with some of these people, because we're building robust systems. So some of the discussions we're having are actually starting to resonate with them.

So we looked at the channels and we go, OK, currently, we're pumping away at the web. Mobile is next. We think, augmented, as opposed to virtual reality is going to be where it's at, maybe chips in the back of your head where you can get a mix of real and generated content to help you do this.

So for the business, that's quite challenging in terms of-- a lot of them are still manual. We were manual three years ago, before we started our big journey. We were manual. And we still had people pushing visas around in trolleys. And we're not the only organisation like that. So it's quite a challenge moving into this digital world. And it's quite a leap for them. They're quite scary.

We came down to two things. We have to automate, and we have to relentlessly automate. It is about completely automating your business processes. We have to outsource stuff. We only want to invest-- because we can't invest in everything-- in automating our end-to-end process.

And there's a big question-- what I'm challenging they want to build a mobile platform. And I'm going, "No, let somebody else build the mobile platform". There's people around the world that do visa transactions on our behalf now. They already have all that stuff. Let's spend the money on automating our internal processes and connect them with the other.

And the other thing to come out of the strategy is the need to reinvest. And it's a sad reality of what's happening with business. We do need to save money on the investments we do. If we invest $10 million dollars, the government expects us to save some money by doing it. And in many cases, that means reduced workforce, reduced FTE.

So where we got to was that our story was this three main steps that you have in terms of becoming a digital business. The first is that internal thing that we do, which is simply moving from paper to online, and then it's paper forms to online forms. That's exactly what we have done. And we spent a fortune doing it, but we had to do it. We had no choice.

What we're now starting to do, the second wave, is where APIs are incredibly important to us, because while we can do a lot of work automating our internal processes, we have a lot of verification tasks we have to do to check that the information is correct. Check you haven't got a bad history with somebody. And we're starting to build APIs so that we can connect to our partners who do that outside processing. So we talk about that as value chain. So we've got the internal process. Then we look at the bigger value chain and we try and automate that.

And then the last for us is actually taking all that up and packaging it up as a digital service that we can then provide out to probably, first of all, some selected partners. But I think the end game is it will just being plugged into whatever your social media that you use is.

And if it involves coming to New Zealand and getting a visa, you just shoot us down the information. We'll shoot you up the supply. And that's why it's going to work. And that seems to be resonating with us. And that, for me, is the importance of the API, not as a point solution, but as part of a long-term multimillion dollar strategy that we're going to become a sustainable business in the digital world. Thank you.


API driven mobile apps

Sergey Efimov developed the Kiwi Hub mobile transport app to help people plan and use public transport in Auckland, Wellington and Christchurch, and talks about the importance of the experience layer in an organisation’s API delivery.

> Transcript of Sergey Efimov's presentation on the Kiwi Hub mobile app

My name is Sergey. So I live and work in Auckland as a mobile engineer and mobile tech lead.

I've studied programming, can't remember when. I think I was born with a keyboard. But recently, I joined Genesis Energy as a tech lead, and we work on some interesting updates for our customers that we're going to release later this year. But as a hobby project during my holidays and weekends, I work on a mobile app called Kiwi App. And in the beginning of this presentation, I will show you just a live demo of this particular app, and a little bit back end services. And then I will share my observations, some ideas how to improve user experience and team efficiency with proper approach to API architecture from the front-end developer's point of view.

So I need to share my screens, I think. Just a second. I'm going to share my screen on my right, so I will be watching this direction. Just a second. OK? All right. Here we see my phone over there. When I open the app, I'm magically in Wellington-- in Wellington and Auckland at the same time. So this application is a public transport app, completely free, available for everybody for three cities, Auckland, Wellington and Christchurch.

Here we can see the real-time schedule when we select a particular bus stop. We can see real time information board. So we can tap on a specific road, and see where the bus is in real time, as well. Or say, zoom it a little bit more, then we can schedule departure notifications. And then the back end service will track this particular bus on your behalf and notify you seven minutes before, well let's say one minute before, this bus is going to be on this stop.

So we can add more stops if we want. Zoom just little bit more. When we tap on a particular stop, we see the real-time schedule just on the map. We can add the stop in the list. So we can regroup them. We can colour them. We can change the name of this stop just in one.

And this app has a journey planner, as well, the same way as Google Maps or something else, but it's this it's journey plan that takes into account the real-time vehicle positions, as well. So let's say we want to go airport just right now, and instantly we see the route and it suggests to us that we need to take bus 18.

Right. We can add the new location, and as you can see when I move the map on the upper side of my screen, there is a location which I selected is going to be a shopper magazine. It's a supermarket. So I can tap on the favourite place and it will show me how can I get there. I can walk, and then take a bus.

So as you can see, this application is quite quick and responsive. This is what users really like, especially on their mobile devices.

So let's have a look a little bit more about the back end services, because this is more interesting for us. Just a second. Right. This is not a back end service, but it's just the analytics around the application itself. So here we can see the real-time information about users. How many unique users per day or in general. And we can see it in the user's location. So this is Auckland. Let's switch to this last fifteen minutes. So here are fifteen minutes, and where people actually use the app in Auckland. In Wellington, as well, we can do the same thing. And based on this information, back end services can create a much higher-level data structures, to create a much better user experience based on this information.

Let's say I am in the app. I can, on my back end, just show you what it looks like when I select different stops. So when I select different stops in the app, you can see that instantly on the back end I see that something is happening. And it is a JSON structure which shows that my identifier, so I don't know who this person is, but I know this is the ID that selects some particular stop just right now. So its a real-time feedback from the application to the applications home, with event-driven design.

And people usually are asking, "How is it possible that you created this app alone for three cities, but some organisations struggle with this?" I think the second part of my presentation demystifies, just a little bit, this idea.

So let me jump to the presentation itself. It is really important for the mobile application to have robust and flexible APIs, and there are three reasons why. First of all, the communication channel between the application itself, and the remote data source is a major bottleneck in the application performance. Mobile users, nowadays, expect a lot from the mobile apps. Mobile software engineers should spend more time on the user experience, animation and smooth transitions, instead of dealing with poorly-designed API responses in the app. The third reason, because the difference between use patterns between desktop website and mobile apps, touch is quite different from a mouse click, if you think about it. Users cannot tolerate more than 100 milliseconds delay when they touch a touchscreen. On the website it's OK to just hit a link, and then wait a little bit, maybe half a second and that's all right, but when you touch screen you want to see something straightaway.

Let's explore the way APIs usually structured in organisations. Typically, you can recognise three distinct API layers. First layer is the system API layer. This layer connects the databases, and communicates with external data sources. A process layer that includes the business logic rules, and data aggregation. An experience layer, which is tied to the specific user experience. In fact, there shouldn't be only one experience layer, but many, carefully crafted to product that consumes it.

What I've seen in most organisations I have worked with is that everyone gets an idea of the system and process layers, but with experience APIs there is always a problem. Sometimes the experience layer doesn't exist at all, or it is built just for the website and does not take into account the mobile experience. But even more often the feature set the client really wants is not aligned with the data available at the experience layer.

What should we do differently, and how can we promote real experience centric API design and a better user experience? Well, first of all, we need to reverse the dependencies, and do not completely rely on APIs that already exist, and always start from the user experience and the feature set. So to give front-end developers an ability to build the experience-centric APIs, please do not delegate this experience layer outside front-end developer teams, and build one experience-API per application.

You probably heard that idea, that the larger the organisation the slower it innovates, or the bigger the software product the more rigid it becomes in terms of adding new functionality. However, this is really a completely incorrect belief, I think. In reality, the larger the organisation or the more mature software product, the faster innovation cycles should be. If it's not the case, then something is wrong with the dependencies between different components and departments.

The way to break these dependencies in IT companies is to give these separate teams, or companies, an ability to communicate with each other using their own set of APIs. So usually smaller teams, four or five people, can develop front end and the back end for the applications.

So do not underestimate the importance of the experience application-specific API layer. Build experience API with the same team which works on the front end product. Use the APIs as a business or management tool to break dependencies between different teams, and the legacy systems. And quite important, do not think about any IT system in terms of maintenance, whether it is a mobile application or back-end infrastructure or service, think about it as evolution. If you follow these steps, you will be much closer to create a great user experience and the best software engineers will be willing to work on your projects.

Thank you.

George Wills from Media Suite talks about the Cruise Guide for the Marlborough Sounds and how open data and API’s are being used to deliver a great user experience and help the Marlborough District Council make better decisions.

> Transcript of George Wills's presentation on the Cruise Guide

I'm going to give quite a different presentation today, which is about the cruise guide and how the Marlborough District Council are using APIs and open data to gather further data from their citizens and make better decisions.

So I'm not going to give you a demo of the app itself during the presentation. But if you want to play with it, go to Feel free to go there now on your phones. And you'll find the app store links and things from there. I won't be offended if you've got your heads down playing with it while I'm talking.

And it's really interesting timing. We actually just released version 2 of the app about three hours ago. So I'm really interested to hear if there's any bugs or anything like that in it. Can you all hear me OK?


Fantastic. Cool. So first I'm going to tell you a little bit about the Marlborough District Council's problems and what they're trying to solve. I'm going to tell you a little bit about the app, what it does, and the APIs it's consuming. And then I'll cover a few things that worked well during the development of this project and a few things that didn't go so well. If we do have any time at the end, we'll try for some questions.

So the Marlborough region has the most coastline of any council in New Zealand. They've got a diverse physical landscape, which ranges from subtropical, subalpine environments and it accommodates some really unique biodiversity with some of the rarest animals in the world.

The Sounds have rich cultural significance for both Maori and Europeans alike. In the last 1,000 years, there's been continuous occupation in this coastal region. And today, the sounds cater to a really wide range of commercial and recreational activities. The agriculture, aquaculture, forestry, and tourism industries use the sounds to generate significant economic value, while recreators enjoy bach life and fishing and diving and boating and much, much, more.

Currently, 80% of New Zealand's aquaculture produce comes from the Marlborough Sounds. The aquaculture industry recently presented a plan to grow the industry from approximately $380 million to a billion dollar industry by 2025. So while this presents a fantastic economic opportunity for the region, it's also likely to create further challenges in balancing the various viewpoints alongside various environmental concerns.

One of the challenges they have in the region, despite having a wealth of the rich environment which provides this wealth of opportunities, the breadth of activities undertaken in the region can lead to quite a lot of conflict, particularly when you have opposing visions for how people would like to use the sounds.

One of the particular challenges MDC have is understanding the recreational uses in the sounds. And this is partly because a large portion of recreational uses in the sounds don't actually live in Marlborough. They come from places like Canterbury and Wellington to their baches. So the Marlborough District Council has a real challenge communicating with them and getting engagement with them.

One book that keeps coming up in environment court hearings as evidence of how the bays are being used recreationally is Keith Murray's New Zealand Cruising Guide. So while this book gives some good perspective on how various bays stack up as anchorages for yachts, it doesn't necessarily take into account various recreational user groups. Not to mention that the book was first published in 1979. So the information in there is getting a little tired.

So the Marlborough District Council had an idea to develop a mobile app which would become a key resource for boaties in the area. And in turn, the council would be able to gather better information about how the Sounds were being used.

So the project itself combines 25 plus open data sets and APIs. As well as the open data we're using, we've also licenced content from Keith's book. And we've also sent drone crews out to take aerial photography and 3D photos. And so we now have a fantastic library of imagery for the area, which can be used for various marketing purposes and, obviously, within the app itself.

So some of the APIs we're using, from the Marlborough District Council we're consuming all the private and club moorings. That's based on their resource consent data. So if you're looking for a club mooring or want to know who's mooring that is out in the bay, you can see it in there.

We've got an API for all their foreshore structures, so that's things like slips and wharves and pontoons. There's data sets for things like special use zones, that's water ski lanes and the like. We've taken all the council-owned facilities, like public toilets and so forth, from other APIs and things like where you can get fresh water from.

From the Department of Conservation, we're taking an API which contains all their campground facilities. And from LINZ, we've pulled together all the various nautical charts for the area and stitched them all together. They have probably a dozen or so different charts which we've stitched together into a single tile server. And then we've got this tile server running on the phone, so that the whole thing works offline when you're out in the middle of the Sounds with no coverage. And we did a really similar thing with the Topo 50 and Topo 250 charts. So if you're into hiking and things, you've got all that stuff that works offline as well.

So we also scraped LINZ's tile servers and took all their aerial photos as well. So we've got high resolution aerial photography in there on top of Google Maps and a few other things that work when you're connected.

One of the things we've got in there is tide predictions. We wanted to make sure that this app was going to do things quite differently to every other app out there. So the initial plan that Marlborough said was we'll just grab an API feed from MetService. But when we looked into it, that wasn't going to give our users a great experience. Because firstly, we wanted our app to work offline. And the MetService API was going require data service to be active. And secondly, we wanted to be able to predict the tide for more than just a few days out. I think the MetService goes 10 days out, so it didn't give us much headroom, and we're trying to take stuff offline. Again, it wasn't so much data we could cache.

And third, and more importantly, we wanted to predict the tide at every single bay in the Sounds, not just at Picton, which is what the MetService API would give us. So we found a data set from LINZ which isn't technically an API, it's actually a spreadsheet, which is updated annually. And we take four years of tide predictions from that spreadsheet for the primary ports of Picton, Nelson, Wellington. And then we sourced all the secondary ports and calculated the offsets from those primary ports, so we've now got 28 secondary ports with accurate tide predictions. And then for each of those 28 secondary ports, we've linked them to all the bays in the app. So now you can click on any bay and see, with an accuracy of plus or minus two minutes, up to four years' worth of tide predictions, all while being offline. So this is a significantly better experience than we were going to get from just grabbing the MetService API.

Some of the other things in the app. We're pulling from the Harbour's Office, we've got a daily feed of temporary navigation warnings near any current navigation hazards, so that allows the Harbour's Office to issue warnings and deploy push notifications directly to app users.

We've got a live feed of marine traffic coming into the app. So if you do have a data connection running, you can identify large vessels as well as course, heading and speed.

One of the most popular features are the live webcams we've integrated. This allows people to see the weather conditions at various remote locations, which aids in their trip planning before they leave the wharf. This is actually something that our users requested after the app went live. So the council invested in having these cameras installed out in those remote locations.

We provided a facility for marine users to report incidents to the Harbour's Office. So users can mark the location of an incident and upload some imagery or video that they've taken of what they've seen and get that back to the Harbourmaster, so that they can go out and investigate.

So there's a bunch more things in the app which I won't to talk about, but feel free to dive in there. And I know someone's just looking at their watch there, so I'll speed up.

Some of the challenges. Some of the challenges we had building this were around the data. A lot of the data presented to us wasn't really fit for our purpose. So we had to do a lot of manual work around mashing up that data.

So in particular, the nautical charts from LINZ. These are provided as single charts. And if you're planning on printing them off and taking them with you, it makes sense to provide them as this one-off thing. But we want an experience which is like a tile server, where they all had to be integrated together in different zoom levels and all sorts of things happening.

So if LINZ were able to provide that as a end-to-end service for all of New Zealand, it would have made our job significantly easier. We also have this maintenance problem every time they update one chart. We have to go and redo the whole lot, and god knows how many other app developers are out there doing the same thing. With their aerial imagery, we actually ended up writing a scraper to scrape their service. It was just easier to go the scraping route than actually use their service, which-- yeah.

So one of the other frustrations was the tide data being provided in a spreadsheet. We would have loved that to be an API. Because we can't fully automate the update process with it being a spreadsheet. The other problem, LINZ haven't actually stated their commitment to updating that spreadsheet, so using it in the future remains a little bit of a risk for us. We're not entirely sure if they will keep updating it and for how long.

There was some data that was missing. So in particular, there was no service that could give us the names, official or unofficial, of any of the bays. So we had to make our own data set using the help of a GIS analyst and quite a lot of local knowledge.

So it took considerable time. And we wanted to release that data as open data, but it actually turned out there was quite a bit of contention about what each bay was called. So MDC were a bit fearful they were going to get lots of complaints if we released that data officially. So they've decided to hold it back. We are able to provide it in an unofficial capacity, so we've named the API endpoint fairly logically in the hope that anyone with some technical skills can find it and use it if they want to.

One other challenge was dealing with licencing. So some content was licenced from this cruising guidebook, and that deal took about 12 months to come through. So the app was developed in late 2015, but we weren't able to actually launch it publicly for another 12 months after that while this thing was held up on the licencing side of things. So open licencing in general saves a lot of time. And thinking about that upfront.

What went well? Well, aside from spending quite a bit of time up in Marlborough on boats and doing user research, what worked exceptionally well in the project was bringing together a really diverse set of stakeholders from different departments in the council, and they all got to collaborate on the design and roadmap for the product.

The product owner for the project or the product owners, in fact, came from the regulatory department. So they're interested in understanding recreational use so they can make better decisions when granting consents and that kind of thing. MDC's web team provided the initial wire frames and they now manage a lot of the content within the app. And they were able to provide quite a lot of insights into various users and groups to talk to.

The IT department there provided project governance and also some API integration support. We worked a lot with the Harbourmaster, who provided a lot of input into the messaging and the types of messaging he needed to get out to his users.

And what was interesting is many of the people in our team actually had quite a lot of sailing experience and experience in particular navigating around the Sounds. So on one hand, that was really useful, but what we actually spotted was a lot of the people who had no experience in this at all kind of kept pulling us back down to earth and stating some really obvious stuff. And it's easy to get carried away. I'm a sailor myself. You get carried away with doing the perfect navigation by the book thing, they're like, well, Google Maps just does it like this, and everyone knows how that works. And you're like, oh, yeah. That's right. Not everyone knows how to sail-- not everyone knows their port from starboard. So it was really interesting having that very diverse group of people designing the user experience.

And also we've had dozens of beta users providing feedback, and we're continuing to get a stream of ideas and praise and criticisms from the public, which is continuing to shape the project. And that's been really, really valuable as well.

So just to recap, what it's providing, it's a data collection to inform future decision making within the council. That's its primary function. But it's also increasing public awareness of issues relating to the Sounds. It's a vital communication channel for the Harbourmaster's office. And it's become a valuable resource for all the users of the Sounds. So any questions?

Beyond APIs

Mix Irving from explains how APIs generally work and challenges us to think about interoperability rather than just building and using more APIs. We currently have a very content-centric model of data flow where people are expected to orbit the many locations of where data is, e.g. websites. Instead we could move to a more people-centric and resilient model where systems are listening for specific interaction types and responding in real-time. As an example see the Scuttlebutt de-centralised social platform.

> Transcript of Mix Irving's presentation on reconceiving interoperability

I am an open-source developer, a teacher, a solarpunk, and a community gardener. I'm keen to talk to you today about interoperability. Interoperability, if you haven't heard the word, just means the ability to interact with other things or other people, other systems.

So I'd like to shift the focus from APIs to interoperability. So to do that, I want to roll back, talk about a little bit about the prior art, the history of APIs, before rolling forward to look at the future and what's beyond APIs.

APIs are not an emerging tech. They've been around for a decade, two decades. I haven't really been keeping track. So we should be learning from them, learning from the mistakes that people have made with APIs, before we try and implement things for government and citizens.

So really quick recap on what an API is. It sounds really jargony. There might be some less technical people in the room, I think we mentioned.

This is my best analogy. We're at the bank. An API is just an interface. It's a way of interfacing with another entity, like the bank. So here I am. I'm a client. Come on in. Here's the server, or the person serving me is the server, the clerk. And the API is this interface here.

I might make some queries. I might ask them some questions. "Can I have my bank statements, please?" So there's a list of queries and legal requests that you can make of that server. And they'll go away and check in their filing cabinet. This is their database.

And there are also, like, a list of legal requests I could make, like "Could you give me Pia's money, or Pia's account details?" And they could say, "No. Who are you? What? Please leave". Also, non-relevant questions-- "Can I buy a dog here?" Like, that's not what this interface is for.

So mapping that into a digital sense-- an API is a just a digital, programmable interface, and it involves robots instead of people. But it's the same language. We've got the client here, which could be my phone. And I've got my Kiwibank app. And I'm making a request of the server. This is the Kiwibank server, who goes and checks their filing cabinet, which is their database, and shows me my bank transactions, or lets me initiate transfers.

So APIs are really exciting, because when you make these things programmable, you give people the ability to display data in different ways. We've really seen some great examples of that today. For example, the-- what was it called? The cruise-- the Marlborough Sounds cruising and interaction is really amazing.

Here's a really simple example with bank accounts. This is Kiwibank. This is my Kiwibank, my well-being account. And I use this to spend things that should be enabling my well-being. And I've got a maths degree, but this is just like numbers. It's like, no good.

So with an API, I can do something like this. I can add a little graph in here, and go, oh, look, the money is building up in my well-being account. Maybe I should up my well-being spending, or whatever, you know?

The frustrating thing is that I know that Kiwibank has an API, because my phone, which is a robot, is able to talk to their robot, and display data. This thing that I made here, I had to, like-- they don't make their API public, so I had to build this manually, teach my robot to go through and scrape this data out of this column, and then build this graph.

And that's like, incredibly annoying as a developer, because I don't just have one bank account. I've got cards attached to Kiwibank, and I've got a mortgage with ASB. And I actually want to dream a little bit bigger. I want to make an interface for Mix which interfaces with both of these and gives me a dashboard that helps me dream about and plan an excellent future. And I can't do it. Like, the banks won't let me do it.

So what's the problem here? The problem is, everyone's building castles or silos. And here's little old me, trying to interface with Kiwibank, which has this big castle wall around it. I didn't have time to draw a moat. Thought it might be a bit messy. But that's basically what's going on.

And it's awkward to get data that's consistent from both of them. They don't really want me to do it. They probably don't want me understanding how much I'm spending on my mortgage and how that's affecting my well-being. So the interests just aren't really aligned.

Here's another way of looking at exactly the same thing. Here's Kiwibank, which is a little bit smaller than ASB. They're just glorified filing cabinets. My data is in those filing cabinets. I'd like it out, please. Can I look at it and interact with it, and weave it together in exciting ways?

So the filing cabinets are going to be a little bit of a theme of this talk, unfortunately. Here's the situation we've got. We've got content bound in a location. We have my data, stuff about my identity and my transactions, stored away in a particular location with some sort of wall around it. And then here's me interacting. Here's other people.

So we've got this situation where people are orbiting these locations. It's this content-centric model that we're stuck with at the moment. And this is all right. What gets difficult is that there isn't just one location that we're circling. There are many.

And so these could be multiple banks that I'm trying to interact with. I believe government's exploring sort of-- I can't remember what you're calling them, but user journeys, where like, I might like to apply for a student allowance as a student. And I want to-- and I don't know where to start. So maybe I start here. I come to WINZ? I don't know where to start. I knock on WINZ's door, and they tell me that I need to get my tax stuff signed off. So I have to go over here, but they've got different forms. So I fill those forms in, but then I need to go over here, which is the university. And they've all got different versions of my identity and records. And it's all quite confusing. So you end up with this a bit of a goose chase around these filing cabinets.

So what have I got written here? Yeah. So siloing of data, having to deal with duplication and de-duplication of like, different versions of the same data about who I am and what is relevant. Debating API formats and specifications-- I think we heard a little bit of that earlier today.

And authorization-- everyone's going to want to know who you are and have different requirements. There are different solutions to that. You could go down the-- well, let's just build another one, another filing cabinet, which tracks who you really are, and then have that talk to these, and hopefully that will work.

Or you could go the route that China's gone, which is like, make the mega platform that everyone plugs into, but the state controls that, which has got interesting, different side effects. But it's interoperable, right? So that's pretty slick.

So we have this content-centric paradigm that we're dealing with, and it's all founded on this assumption that data has to be bound to a location. I have to go down to Immigration New Zealand and knock on them and ask them to access their paper files, or go to, and access the files through some API or some form. It's all about having to go somewhere to get something.

But there's a possibility that we don't necessarily need to live in that world. So this is a bit of a shift sideways. There's a bunch of cryptography which has come out in the last 10 or 20 years as well. Easiest way to describe it is Rumpelstiltskin.

Quick primer or refresher on the story of Rumpelstiltskin-- it's a fable about a cheeky imp who makes a deal with someone. The details of it don't matter too much. But basically, he's going to take the firstborn child. And he's like, unless you can guess my name. And she discovers Rumpelstiltskin's name and says, perhaps, she said, your name is Rumpelstiltskin. And with that, because she knows his "true name", she can undo the magic of this agreement she's made.

So it turns out that there's also a thing of like, true names, more generally in fantasy writing, where there is the true names of people, but there's also the true names of objects, so that if you know the true name of a rock, you have magical power over it. If you know the true name of the wind, you can shape the wind.

Thanks to the magic of mathematics and cryptography, these things really exist. For people, it's public/private key cryptography, and for objects, there's this concept of hashing algorithms. You don't need to know what they're called.

But it means that we can now tell stories like this, where instead of having to think about me filling a form and it being filed in a particular cabinet, I can apply for a student loan by saying, I would like to apply for a student loan, into this sort of conversation circle. And this piece of content has a true name. It's the form that I filled in. And anyone who knows that name can summon it to them from the peer-to-peer cloud.

And it happens that the relevant parties-- could be WINZ or IRD-- are listening to me. And they say, "Oh, that's interesting. Yeah, that's all good. Go ahead." So there are no filing cabinets. And I didn't necessarily even need to know where to go.

More details about privacy and security-- don't have time in 10 minutes.

So what this can look like at a bigger scale is, people all around New Zealand saying things or preparing documents or forms or whatever like that, and then people listening to those and interacting with them, and in quite a conversational way. And so this is a shift from a content-centric to a sort of more people-centric data flow.

And because there are no filing cabinets, this also has really interesting things here-- resilience side effects. So this isn't a fairy tale. It's not fantasy. People in New Zealand are already building this. This is a blogging platform built on this, on the internet.

People have got content that they're already writing. I'm having a conversation about accessibility with interfaces with someone in Australia. And I'm having conversations with other dads about how to be a new parent, because I'm a new parent.

People are running workshops on mycology, and building things with mycology. I've got my talk also running on this system. So if anyone wants to use any of the resources or sweet drawings that I've done, that's all open-source. So it's out there, not in a filing cabinet, but drifting around.

So in summary-- so that's called Scuttlebutt, by the way. Happy to talk more about that afterwards. In summary, let's learn from the past. Don't build APIs where you have to like, build meta APIs to use the APIs. We can do something better.

Let's build people-centric platforms. Let's build systems that are more resilient. If you build in a different way like this, it'll be resilient to earthquakes. You don't even need the internet to run it. And it'll be more flexible. Thank you.

Brenda Wallace from the Service Integration LabPlus team at DIA talks about event buses and why they can be better than APIs.

> Transcript of Brenda Wallace's presentation on event buses

Ko Brenda ahau. Kua mahi au i Te Tari Taiwhenua mo rima marama.

So I've worked here for five months most of which was Christmas holiday, so it's been quite an experience working for gov. You want me to stop moving, OK. So I've done a lot of API development. And I don't want to discourage you people from going back to your ministries and adding more APIs, but sometimes API isn't the solution. There's traditionally-- an API is a big, giant server, and there is a client who says, hey, give me this thing. That decides, yes, I'm going to give you this thing. And it gives you a response. So it's like request, response, request, response.

Sometimes this makes absolutely no sense, because for example you might be waiting for something to happen. And when it happens, you can't wait a day to process it, so you end up writing clients that, for every 30 seconds say, "Hey, has it happened yet? Hey, has it happened yet? Hey, has it happened yet?"

And it gets really ridiculous, and you cause global warming basically. And the sea rises, and we all drown. So sometimes this is not a good idea. What you actually want is you think, "Hey, server, could you just tell me when it happens? I'll wait". But servers don't do that. That would make it a client.

So there's another concept out there called event-driven. If any of you people write JavaScript, you're doing it all the time anyway. But instead of you going, hey, server, has it happened? You say, hey, the ministry, whoever has this information, when it happens, publish the event.

So over here you have all your infrastructure that is an event bus, and when it happens, you publish the event. And the client says, "Hey, event bus, when an event of that type happens, tell me about it". So suddenly this whole coupling between server and client goes away.

I need to give you an example to make it a little bit clearer. Let's say the server is a city council, and they process-- someone tells them, hey, the light is broken in my street. So that is an event that someone has told the city council. And they say, "Hey, event bus, tauranga.suburbname.streetlight.broken". Completely separately down the road in Taupo, they also publish taupo.streetlight.broken.

You, as a person who cares about street lights being broken, can subscribe to events that are only Tauranga, or only street lights broken, or only tauranga.streetlights.broken, or only Taupo. You can decide what you care about. The server doesn't need to know. And you, as the person who controls the drones that fix the streetlights-- or NZTA, who route people through different routes, because maybe the event is a sewer explosion. Who knows?

You don't need to know is NZTA listening, is Mix with his dashboard listening, is Google Maps listening? You don't have to care. You just publish the fact that Tauranga has a streetlight broken.

And suddenly it all becomes event-driven. There's no more polling. There's just a tiny snippet of code that publishes a message. A tiny snippet of code that says, when I do get a streetlight broken, call the drones, or reroute my maps, or anything like that. And you have a much nicer infrastructure.

So don't stop building APIs. I mean, an API is better than no API. But when you do, think maybe it's an event. Maybe I can build an event bus. And if I can throw some products up there-- RabbitMQ, which uses the APP protocol-- Mosquitto that uses MQTT. But there's a bunch more out there.

I've used it extensively at Weta for whenever an event happens, such as there's a new drawing of Iron Man's helmet. So the renderer needs to re-render. And then when the renderer is finished, it publishes the event, I finished rendering. It doesn't care or know who wants to know about a new helmet. It just publishes it, and everyone else cares-- who cares about it finds out. So there we go. That's event-driven. If you're going to design a thing, think about doing it that way.

Post your comment


No one has commented on this page yet.

RSS feed for comments on this page | RSS feed for all comments