API guidelines — Part A: API concepts and management 2022

APIs (Application Programming Interfaces) enable reuse of data, transactions and rules. This creates an opportunity for greater cooperation and interoperability between agencies to dramatically improve service design and delivery.

1. API concepts

1.1. Why an API

Interoperability between government agency systems and customers today involves a wide complex range of mechanisms, protocols, standards, technology and so on, and the idea of using APIs is to decouple the interface from this complexity as much as possible.

A clearly defined API specification provides a common language and ensures a common understanding of the interaction. So, with APIs, the consuming application only needs to understand the interface and does not need to understand the underlying technologies. This greatly simplifies the interaction and encourages interoperability.

1.2. What is an API

An API is a computing interface that defines a shared boundary across which 2 or more components exchange information. In practice, an API is generally a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. It can be considered as a:

• means of requesting and retrieving information from a system or server so that it can then be presented to the user in a context / process-specific way — for example, in a mobile application or web application
• way of de-coupling system-to-system interactions
• contract between the application developer and the provider describing what information or functionality they can gain access to and how that access is provided.

APIs are commonly categorised as shown in table 1:

1.3. Basic API architecture

Figure 1 shows the basic architecture of an API and its use.

Detailed description of figure

Figure 1 shows the basic architecture of an API. The diagram illustrates the following workflow processes:

• An API provider (for example, a government agency) owns the resource (information or functionality) in applications that will be exposed by the API.
• API developers build the API — they start by defining the interface specification, and then they build the API.
• Application developers create new software, or adapt existing software, for devices such as smartphones, computers and appliances, to use the API. This software, known as an API consuming application, uses the API to gain access to the resources the API provider is offering.
• Finally, customers use the API consuming applications. The application developers, the API consuming applications and the customers are referred to as API consumers.

View larger image (PNG 114KB)

Figure 2 illustrates the API architecture for the example of a funded healthcare eligibility check. Table 2 details the API roles for this example.

Detailed description of figure

Figure 2 shows the API architecture for the example of a funded healthcare eligibility check. The diagram illustrates the following workflow processes:

• The Ministry of Health (MoH) is the API provider. MoH has developed an automated eligibility check application that determines whether a patient is eligible for funded healthcare or not.
• The MoH API developer develops an API that takes the information from the automated eligibility check application to a GP’s Practice Management System (PMS).
• The PMS developers (application developers) enhance their PMS system to call the API and develop business rules for what to do if a patient is not eligible for funded healthcare.
• The GP (customer) uses the PMS (consuming application) which uses the API to determine whether the patient is eligible for funded healthcare and to decide how much to charge the patient for their visit.

View larger image (PNG 131KB)

1.4. API privacy

Clearly, some APIs will be for internal government use while others will be for external or public use. The types of information offered by these different types of API will be limited by the privacy act and security concerns.

Privacy laws that define the management of customers’ information and the related consent policies are now at the forefront of many organisations’ obligations as legislation mandates how this is applied along with the related penalties.

Globally there are a number of privacy laws that stipulate strict compliance for organisations within their jurisdictions, but it is important to note that these laws can apply to organisations outside the physical borders, for example the Europe Union’s (EU) General Data Protection Regulation (GDPR) covers any global organisation that might deal with a customer who resides in the EU.

New Zealand privacy legislation is dictated by the Privacy Act 2020.

Privacy Act 2020 — New Zealand Legislation

The following global privacy laws should be considered if an organisation manages customers who reside outside New Zealand.

1.5. Needs and drivers

So why build an API? In what situation is an API the right thing to develop? There is an increasing drive towards government agencies delivering APIs as part of open data (Data.govt.nz) and ease of digital interaction with government. But different government organisations have the following different drivers.

• Moving towards a collaborative model of service delivery — enabling agencies to participate in external business processes.
• Improving customer interactions with government — enabling integration with partner agencies at a system level rather than via humans.
• Moving from retailer to wholesaler of services — supporting integration with third parties and enabling them (rather than the agency) to build the customer-facing aspects.
• Using cloud services — ensuring reliable and secure information exchange with cloud-based, commercial off-the-shelf (COTS) solutions.
• Improving access to information — providing a more robust interaction model than the current practice of data and screen scraping.
• Meeting the goals of open data — using APIs to open public data to public access, enabling the private sector to create their own solutions based on public data.
• Improving quality of information — providing a reliable single source of the truth and a more robust interaction model than the current practice of regular bulk information sharing.
• Exploiting emerging technology — encouraging uptake of new and innovative technologies to keep pace with customer demands and expectations.
• Enabling channel shift — supporting agencies in their desire to make APIs their main web channel in preference to developing agency‐specific web user interfaces (UIs).
• Contributing to the business growth agenda — helping to grow competitive businesses within New Zealand in the information-based economy.

1.6. Why have API guidelines

While some NZ public sector organisations have been producing APIs for a while, others are taking their first steps in offering APIs for public use. It is useful to provide a reference and set of guidelines to support this API development in order to:

• encourage consistency across government API offerings and thus making it easier for third parties to build solutions using government APIs
• avoid different government organisations developing or delivering idiosyncratic APIs
• generate awareness of what is needed to support APIs as a delivered product to private sector customers — for example, levels of service and support capabilities
• capture API best practice for reference by the API development community, indicating where commonality is required, and which areas allow for more flexibility
• reduce disruption to application developers as government APIs evolve
• reduce effort for agencies by simplifying the process of developing and delivering on their API strategies.

The Strategy for a Digital Public Service recognises the need to collaborate and co-create with partners from inside and outside government, including the private sector and Māori, in order to unlock the value of information to help solve complex problems and generate innovative ideas.

The development of APIs is considered a key part of this picture in order to improve access to public services and deliver a joined-up experience to the customer. This approach requires collaborative service delivery, where front-end and backend capabilities may be developed separately — partly by the government sector and partly by commercial entities or NGOs — and delivered in a coordinated fashion to offer a seamless experience to the customer. This change in approach can obviously impact the business function of an agency.

If we look at API delivery in an all-of-government context, we see that the initial focus tends to be within an agency’s sphere of influence, as part of the business systems they deliver and processes they perform. APIs are seen as a means to an end, quite often driven from a technological perspective.

While organisations across government have different levels of take-up in terms of APIs, there is a common pattern of evolution, which can help when developing an API strategy and road mapping delivery of APIs.

1.7. API evolution

An organisation’s development of APIs tends to start from an internally-focused perspective that concentrates on existing internal resources (data, functionality). Over time this perspective broadens to encompass the needs of their sector, then all-of-government and beyond. A potential roadmap for the evolution of government APIs over time is illustrated in 5 main stages in Figure 3, and aligned to examples from mobile banking’s evolution.

Detailed description of figure

Figure 3 is a flow diagram that illustrates (from top to bottom) the evolution of government APIs, from internally-focused APIs to future capability, and compared with examples from the evolution of mobile banking. The main stages are as follows:

• Parochial:
  • Read information
  • Request action
  • Example: mobile banking — visibility of bank balance.
• Integrate:
  • Inter-agency process support
  • Real-time data
  • Example: mobile banking — real-time bank balance plus pay existing payees.
• Modify:
  • Create new info
  • Update existing info
  • Example: mobile banking — create and pay new payees, and update contact details.
• Primary channel
  • APIs are the primary source
  • Reduce user interface (UI) development
  • Example: mobile banking — all banking capabilities available (via API).
• Automatic:
  • Machine discoverable
  • Machine consumable
  • Example: mobile banking — unknown.

The stages are described in more detail in sections 1.7.1. to 1.7.5.

View larger image (PNG 60KB)

1.7.1. Parochial

Initially, parochial APIs are developed to enable programmatic access to existing information stores (for example, ‘see radio spectrum usage’) or to request an action from an agency, which spawns an internal business process (for example, ‘request patent renewal’). These are built from the perspective of the resources the agency holds, not from an all-of-government perspective.

High transaction volumes are often a driver for agencies developing parochial APIs. The APIs are designed either for consumption by systems within the organisation or by selected consuming applications outside the agency. Access to information may also support some filtering (for example, ‘view available or free radio frequencies’). This step of the evolution may be bypassed by organisations whose drivers are focused on external integration.

1.7.2. Integration

Opening up APIs for integration is the next step, where business processes that span government organisations are acknowledged and supported. This often encompasses a move from batch processing to real time data update, with the associated mindset and business process change.

APIs form another digital channel, alongside the standard web user UI channel that supports the majority of interactions, with the paper channel being retained only to support exceptions.

1.7.3. Modify

APIs are then created that start to support authorised modification or addition of information to information stores. This is either to support direct update by the end customer (via web form), or by third parties acting on their behalf (with delegated authority — for example, mobile apps). APIs are at this point becoming one of the core products that an agency releases, offering transaction handling and taking over from web interfaces.

Ideally private sector organisations increasingly use the APIs to incorporate public sector capabilities into their commercial offerings, migrating government from the role of retailer to that of wholesaler.

At this stage of the API evolution, it is important to maintain and govern a resource model to ensure consistency across APIs, and potentially across agencies, if a sufficient number of agencies have reached this level.

1.7.4. Primary channel

Next, APIs become the primary channel for information and request for action. This fosters innovation by opening up resources to third parties who have not previously had access, such as commercial entities and NGOs.

This stage of API evolution starts unlocking the value of information and enabling compliance or interaction with government processes to be built invisibly into everyday applications (for example, automatic GST returns via accounting software). It also moves the onus of UI development from government to the marketplace, allowing new and intuitive means of access from mobile devices, smart phones, domestic appliances and so on, to be created.

At this stage, it is likely the marketplace will encourage government to start developing a shared resource model to help make it easier to consume APIs from different agencies.

1.7.5. Automatic

Finally, we move to the automatic use of APIs, where APIs are both machine discoverable and consumable, requiring minimal developer input for effective delivery of capability to the customer. It is difficult to predict the impact this will have, as there are no examples to date of this kind of capability.

1.8. Business change

The building of an API channel opens up an agency to business process change that influences the ways they work internally and with partner organisations. It can also alter the main point of contact with the public, or add a layer of abstraction, as API-consuming applications replace direct contact with customers. Hence, change management will be paramount in the development of this new API channel.

While most government organisations are looking at API development from the perspective of their own needs or the needs of their sector, there is an emerging consideration of APIs in the context of all-of-government integration (federated service delivery) and joined-up capability to support customer-centric public services.

Once the fundamental building block APIs are in place to assist with integration and information sharing, it enables commercial operators to innovate and combine multiple services to provide value-add customer-focused end products. Is it possible to foresee a future where public interactions with disparate government agencies are automatic, seamless, and built around the end user’s ultimate goal (for example, setting up a business)?

Currently, as shown in figure 4, a member of the public acts as the integration point between agencies, supplying the same or similar information to each agency (name, contact details) while trying to achieve their objective and having to develop a mental model of each agency’s business practices to navigate by.

Detailed description of figure

Figure 4 is derived from Federated Service Delivery (FSD) reference architecture. It shows a member of the public (a customer) in the middle of the diagram acting as the main integration point between agencies. The customer is supplying the same or similar information to 4 agencies through the agency interfaces, which could be by human interaction, paper or web-based forms or mobile applications, to achieve their objective. Meanwhile, a thought bubble coming out of the customer shows they also have to develop a mental model of each agency’s business practices to navigate the process.

View larger image (PNG 71KB)

Figure 5 shows that with the gradual emergence of an API layer across government, the need for this human information sharing mechanism should reduce, moving the integration into the system layer. Coordination across this layer will be fundamental to seamless delivery of federated services.

Detailed description of figure

Figure 5 is derived from FSD reference architecture. Compared to in figure 4, the customer is no longer the central point of integration between agencies. There is 1 connection point from the customer to the application layer, which includes various devices such as smartphones, tablets and desktop computers. These consuming applications perform the integration between the 4 agencies on behalf of the customer. The agencies in turn offer APIs to the application developers through the API layer.

View larger image (PNG 48KB)

There is also a move towards government as the wholesaler rather than the retailer — in other words, provider of the information at the programmatic layer (API) rather than at the presentation layer (for example, website). If the APIs were available, software packages that customers already use could be enhanced to complete many of the obligatory government interactions automatically, in the background (with customer permission).

The commercial world is seen as having the means, experience and drivers to develop effective ways of interacting with the public — so, by opening up resources via APIs, government agencies can encourage innovation and create opportunities for more intuitive and supportive channels of working for the customer.

There will still be instances where government needs to act as an impartial intermediary and offer capabilities that are unbiased and independent (for example, patent examination) or offer basic capabilities for organisations that cannot afford anything complex, but these should be the exception rather than the norm.

It is also recommended that any action that legally commits the customer (for example, GST return submission) requires a manual step so that such commitments are customer controlled.

1.9. Potential impacts

1.9.1. Potential policy impacts

• Legislation and regulations — APIs must align to the legislative or regulatory requirements on the agency. In some cases, legislation and / or regulations may limit the opportunities for agencies to use APIs. For example, legislation may not allow for electronic submission. Conversely, an API may introduce new risks that are best managed through legislation or regulation. For example, if there is a bug in a software package, which means the information submitted electronically is incorrect, who is liable for the error and the resulting penalties or criminal offence, if any?
• Privacy — Another area of legislation that APIs must align with is the Privacy Act 2020. Agencies with APIs that involve personal information will need to consider the privacy implications. If appropriate, an agency may choose to undertake a privacy impact assessment to understand the privacy implications of an API. For example, the API may introduce the possibility for amalgamating information in ways unpredicted by the agency. Additionally, the Privacy Act may impose limitations on APIs. For example, the methods available for uniquely identifying individual customers are limited by the Privacy Act.
• Identification — Does the agency need to (uniquely) identify any, or all, of the API consumers? What is the appropriate mechanism for uniquely identifying the customer who is registered via an API consuming application?
• Risk appetite — APIs have the potential to introduce new risks to an agency and / or remove some risks. Different API designs may have different risk profiles, which need to be understood.
• Business analytics — One side effect of APIs is that more and more information is exchanged electronically, potentially creating new information stores. These new information stores provide new opportunities for amalgamating personal information and sharing information.
• Terms of use — What terms of use are appropriate for your API? Consideration should be given to the purpose for the information exchanged via the API and the limitations on its use by the application developer for other purposes. Additionally, consideration should be given to how compliance to the terms of use will be enforced and monitored.
• Pay-per-use — While it is possible to consider pay-per-use charging for APIs where commercial entities will be making money from the services offered, pay-per-use can have a negative impact by impeding take-up. Even requiring a one-off charge as an on boarding fee can impact take-up especially by smaller application developers and NGOs. There may also be some legal restrictions to charging for use of APIs. (Pay-per-use should be differentiated from transaction fees or official fees.)

1.9.2. Potential contractual impacts

• Creating new contracts and Memorandum of Understandings (MOUs) — Commercial use of APIs may require more rapid contract and MOU development to encourage uptake and to help ensure all the intended consumers are supported. Contractual arrangements that take too long to organise or have onerous conditions will discourage commercial uptake.
• Extending existing contracts and MOUs — A new API may have implications for existing contracts or MOUs. As the integration approach has the potential to change, so too does the contract or MOU.
• Structure of contracts and MOUs — The structure of a contract or MOU may need to change in line with the API development approach. For example, if the development approach is agile, with frequent API releases, then the structure of the contract or MOU should have the flexibility to easily allow changes to maintain alignment with a rapidly evolving API.
• Enforcement of contracts and MOUs — APIs often make information available to consumers in the context of specific terms of use. For example, personal information about the customer is made available from the API to consuming applications for a specific purpose. What are the implications if the application developer then uses the information for other purposes?
• Service levels — APIs often require service level agreements (SLAs) with application developers and suppliers. SLAs are important to understand and will likely evolve over time as the API matures. MOUs and contracts should cater for this scenario.
• Coverage of MOU — Existing MOUs for information sharing may be sufficient initially, to cover an application developer’s planned use of an API, but once an API is exposed new developers not covered by the MOU may request access. In this situation, careful consideration must be given to whether the MOU should be modified or access to the API denied.
• Extent of sign-up — When an API is offered publicly, and application developers register for use, it is important contractually to know whether the individual is signing up to an API in their own capacity or on behalf of an organisation.
• Onward information handling — It may be appropriate to contractually impose limitations on the on-going use of information exposed via APIs. Application developers can cut, amalgamate, derive metrics and present information as they choose, once they have obtained data via an API unless you impose limitations.
• Responsibilities definition — Agencies may wish to clearly contract responsibilities with application developers to ensure customers of their applications are made aware of their legal obligations in regard to use of agency APIs (for example, changing tax information via their application).
• Information currency — Some application developers may be tempted to use the API to update their own local caches of information. Depending on the information update period, this can be risky as it means they are working from potentially obsolete information.

1.9.3. Potential organisational impacts

• New services — If this is an agency’s first foray into APIs there may be a completely new model for service delivery, potentially with the need to support new types of customers (for example, software developers) and product release cycles. It is important to consider the organisational implications of this new model.
• New processes and procedures — In addition, APIs may introduce new ways of working, the implications of which need to be understood. For example, if the API is automating a manual process then the implications of this new automated process need to be considered.
• New skills and techniques — An API channel for service delivery requires a new set of skills and techniques to manage the application developers and the communications with application developers, for example, incident resolution.
• Service delivery partners — An API channel opens the opportunity to develop relationships with third parties who deliver services on behalf of the agency. These service delivery partners may need to be engaged and managed in new and different ways.
• Availability — The availability of an API should be no less than the availability of the equivalent agency online service or website, as this will have already set an expectation from the user community. An API may need to be available 24 hours a day, 7 days a week (24 / 7), but consideration should be given as to whether support for the API also needs to be 24 / 7.
• Service levels — Opening an API channel may necessitate an agency to offer a level of service, where previously there has been no such need. Commercial experience and knowledge could be required in order to define realistic and achievable service levels that serve everyone. These service level changes may require additional staff to cover increased support hours, for example. There is also a need to measure, monitor and report back on performance to ensure SLAs are met.
• Support services — There may be a reduced need for agency support services, where consuming applications replace agency presentation layers, moving customer calls from agency support staff to the application developers.
• Principles — In order to incorporate all-of-government thinking into API development it is useful to have a set of business principles that should influence the way APIs are built and their usefulness over time.
• Governance — API governance helps save time and money because it ensures that APIs are built proactively to achieve specific goals and bring value to the agency. API governance also helps agencies make intelligent decisions regarding API programmes and establish best practices for building, deploying and consuming APIs.

2. Principles

These are a set of principles that are considered good practice when designing, implementing and operating APIs. The New Zealand Government Digital Service Design Standard provides a wider perspective and set of principles that should also influence the design of APIs and the services they support.

Digital Service Design Standard

2.1. Design for the consumer

APIs need to be developed with the consumer primarily in mind. The application developers also need to be considered because, of course, if the API does not meet their needs then they will not develop consuming applications that use it. This leads to APIs being developed as generic as possible in order to meet the basic needs of all potential consumers.

API developers should not try to predict how the consumer will interact with consuming applications and should leave the application developer to innovate. By designing APIs for the consumer, agencies are likely to build APIs that are intuitive and easy to use, thus ensuring uptake of their APIs and encouraging access to public information.

Initially, application developers will be the main users of APIs. Hence development and delivery of APIs should be geared around making it as easy as possible for developers to discover, understand and develop against those APIs. So, APIs, along with the associated onboarding and support processes, should be simple to understand and well described.

Some examples of this principle in action are:

• ensuring a low barrier to entry so it is easy to start using the API
• providing sandbox APIs so application developers can try out APIs and develop in parallel
• being responsive to feedback and bug reports
• providing automated onboarding processes, as manual processes can limit take-up
• providing prototyping tools and support for development
• ensuring the funding cycle does not introduce a bottleneck for uptake within government
• selling the concept to the consumer early on so they create demand that industry needs to meet
• creating an atmosphere of competition in industry for take-up of the API
• creating a software development kit (SDK) to support an agency’s APIs, including examples.

2.2. Design-driven development

This builds on the principle of ‘Design for the consumer’ and could also be phrased as ‘specification-driven development’ because the interface specification for the API is written first. Designing the interface does not require full design of the code that will sit behind it. The interface can be in place without the functional capabilities being built and yet still be useful.

By defining the interface first, there is a known integration point, which both the application developer and API provider can refer to and build to. Potential application developers can use the specification to assess whether the API will meet their needs, or if further information or parameters are essential to them.

The process of creating a specification before development forces the API developer to properly consider the purpose and content of the interface they are providing, before coding starts. Taking a design-driven approach simply means that the API design should be performed before development begins — it does not mean that development is hindered in any way.

There are a number of tools that assist with this process, however the tool to create the specification should be of little significance, the act of creating the specification is what counts.

2.3. Co-design

This principle is the natural extension to both the ‘Design for the consumer’ and ‘Design-driven development’ principles and includes collaborating with the consuming application developer community when designing the interface. This is important to help meet the Strategy for a Digital Public Service aims to co-create with partners and make business engagement with government more efficient, not just for business as a customer of government but also where business works together with government. Co-design works as an enabler to business innovation and supports better interaction with government.

Application developers are one of the primary customers for the API and, as such, are a primary source of requirements. Working with application developers to define the requirements and to design the interface ensures the API will meet their needs. However, identifying potential application developers and understanding the demand from the market can be difficult. Careful consideration should be given as to the best approach to engaging with the market and identifying your potential application developer community.

Additionally, it is strongly encouraged that application developers start to produce API consuming applications based on the interface specification as early as possible. This agile or iterative approach helps ensure real-world feedback is incorporated into the API design as early as possible.

Completeness is not necessarily the goal, especially in initial APIs. The goal should be to get early partially complete releases out, defining the limited capability they offer, to enable consuming application uptake. Development needs to be flexible and agile to adapt to early adopters’ feedback on the identification of pitfalls and issues. However, early releases should be tested and stable so as not to impede uptake. The aim is to try, then adapt, rather than waiting to release a fully functional API.

2.4. Future-focused design

Most agencies will have a variety of legacy systems that they need to continue to support and service. It is important to remember that business, technology and application architects should be designing for the future of their organisation, and not ‘hamstring’ their APIs under development by designing them to work in the way the legacy system currently works, or to tailor APIs so that they work perfectly with all legacy systems. The aim is to be future focused (while still pragmatic) and develop APIs to meet future needs.

These needs will be agency specific but may include a drive to move to a wholesaler rather than a retailer role, where the agency reduces its web presence in favour of enabling commercial entities to create applications, or add richness to existing applications, through access to agency APIs.

2.5. Dogfooding

When building an API, there is always a danger of building the wrong thing in the wrong way for the wrong people. This is especially a risk in the absence of external developers driving or informing the development of the API.

The simplest way to ensure an API is useful and consumable is to build the API as part of delivering a larger-scale internal business support system such as a web application. In this way, the customer and application developer are internal, and the first principle ‘Design for the consumer’ applies.

The best way to design an API is in collaboration with the potential consuming application developers. The best way to understand and address the weaknesses in an API’s design and implementation is to use it in a production system. So, wherever feasible, design an API in consultation with application developers but build it in parallel with an accompanying integration of that API to ensure it is fit for purpose — in other words, build for inside use, then expose. This has the added advantage of meaning that the cost of API development is covered throughout the build of the business support system or integration mechanism, reducing the need for extra funding.

2.6. Stability and backwards compatibility

It is important that APIs have stability (are available and work consistently) and support a velocity of change that is acceptable to the application developers. Early versions of APIs should be available via pilots or on developer portals so application developers can work them and identify areas of instability before an API goes into production.

Application developers will not always be able to adapt to new capabilities or changes to existing interfaces as quickly as the API providers might wish, due to organisation priorities and funding. Hence, minor changes to APIs must always be deployed as fully backwards-compatible upgrades.

For major changes, which are not backwards compatible, the old API version should be maintained alongside the new version for an appropriate period to allow all-consuming applications to transition. By monitoring usage, it should be possible to assess when an API version can be deprecated, either because it is no longer being used or because the usage pattern does not warrant maintaining that particular version.

In any case, it is important to clearly communicate with your developer community and manage expectations as to the longevity of a particular version of an API.

2.7. Privacy and sensitivity aware

APIs are used extensively for passing information on, so it is important to consider the information privacy and sensitivity aspects of data being passed to and from APIs to ensure that data is protected adequately.

Consideration should be given as to whether a privacy impact assessment and / or a security risk assessment is appropriate for the API during each stage of development, from concept through to implementation.

Privacy Impact Assessment Toolkit — Privacy Commissioner Te Mana Mātāpono Matatapu

Privacy, security and risk

For example, if the API is providing programmatic access to publicly available information, the privacy considerations are likely to be minimal and the security considerations limited to the usual suspects, like the Open Web Application Security Project (OWASP) top 10.

However, privacy and security considerations become hugely important if the API is providing programmatic access to private, personal information. In this situation, it may be appropriate to do regular assessments, especially early in the concept phase to ensure any privacy or security constraints are understood before design.

There is also the issue that with ease of data consumption comes increased ability to combine data from different sources, which increases privacy risks and the potential for unintended information leakage.

2.8. Well managed

As API take-up increases over time, there is more likelihood of API change, redevelopment and adaptation to meet new needs. A well-managed API should handle regular change.

API management gives an agency the capability to deliver good version control capability and forewarn application developers of changes that may impact them, including failures and outages. For this reason, it is important that all application developers are identified, even if the API is considered public.

3. Key characteristics of an API

At its heart, an API is, as its acronym suggests, an application programming interface. This simply means that an API is an interface that enables software inter-communication. The purpose of these interfaces is to enable safe and reliable communication in a standards-based way.

An API should strive to deliver these functional and non-functional requirements:

• Functional requirements:
  • security
  • usability.
• Non-functional requirements:
  • reliability
  • testability
  • scalability.

3.1. Reference architecture

Part A, and companion Parts B and C, are based on the reference architecture information in this section. Due to the nature of these guidelines, the reference architecture addresses numerous aspects of an API and is reasonably complex. Depending on their circumstances, agencies may choose to:

• use this reference architecture
• simplify the reference architecture to better suit their needs, or
• develop their own reference architecture.

Figure 6 illustrates the reference architecture, with the concepts further expanded, layer by layer.

Detailed description of figure

Figure 6 illustrates the layers of the API reference architecture. When designing and developing an API, analysis is required across all layers of the reference architecture to meet the needs of all parties. From top to bottom these layers are as follows:

• Consumers (consuming applications) — discover the API by using the interface specification.
• Interface specification — the layer between consumers and the API. This needs to be published for consumers to discover the API.
• API — provides authentication, course-grained authorisation and validation / threat protection, and may perform simple orchestration. It makes sure the interface specification is maintained and published. It is stateless.
• Application / logic — performs platform authentication, fine-grained authorisation and validation, and may perform complex orchestration. It is stateful.
• Data — performs platform authentication. It is stateful.

Some layers are linked by:

• context — linked from:
  • the Consumers to the API layers, and
  • the API to the Application / logic layers
• analytics — linked from the API to the Data layers.

Trust exists between individual layers, but decreases the further up the model you go, with a high level of trust in the lower layers (data, application / logic) but minimal trust in the upper layers (consumers).

These layers are described in more detail in sections 3.1.1. to 3.1.9.

View larger image (PNG 54KB)

3.1.1. Consumers

Relates to the usability functional requirement.

Consuming applications can be anything that uses an API. Consuming applications ‘drive’ your APIs.

Application developers build the applications that consume your APIs. When designing an API, the usability or function of the API should be aimed at this group.

Interface specification must be published for it to be discoverable. API discovery refers to the way that your APIs are understood by an application developer. Application developers like to see an API or interface specification in a format that they are familiar with. The functional and non-functional behaviours of the API should both be well described. Refer to Part C: API development 2022 for details.

The consumers component has a low level of trust.

3.1.2. Interface specification

Relates to both the usability and security functional requirements.

An API interface specification is a technical description and reference model for an API. The specification is used most commonly by application developers to understand the technical aspects of an API. However, interface specifications should also be provided in a machine-readable format. Refer to Part C: API development 2022 for details.

3.1.3. API

The API component of the reference architecture is multifunctional. It provides API authentication and authorisation, preferably using a standard approach. Refer to Part B: API security 2022 for details.

To protect an agency’s resources, the API component should perform threat protection and quality of service (QoS) functions. This could be in the form of ‘throttling’ requests, schema validation and common vector attack protection (Structured Query Language (SQL) injection, Cross Site Scripting). This functionality should not be seen as a replacement for other defences, but an augmentation to those defences.

In some cases, simple orchestration may be performed within this component. An example of simple orchestration is a ‘mashup’ of 2 backend services or applications into a single API.

The API component should be responsible for maintaining interface specifications and publishing these to the interface specification component.

In a bimodal IT model this component emphasises agility and speed.

This component has a medium level of trust.

3.1.4. Application / logic

This component is where complex business logic is handled. In many cases this will be a system or group of systems that exist at an agency which do not conform to a common standard. This component is where fine-grained authorisation should be performed based on business logic, which the API component should have no knowledge of. In a bimodal IT model this component emphasises safety and accuracy.

This component should verify the authenticity of the API component, referred to as ‘platform authentication’.

This component has a high level of trust.

3.1.5. Data

The data component represents one or more sources of data within an agency. It does not necessarily need to be a traditional data store or database — it simply represents the fact that an agency will inevitably have data that can be represented in an API.

This component traditionally verifies the authenticity of the application component, referred to as “platform authentication”.

The data component has the highest level of trust.

3.1.6. Context

Context can take many forms and it is simply a way of providing contextual information for the request to downstream components that may require it.

The main purpose of context is to prevent layers of the architecture having to look up information that has already been gathered elsewhere by something that the component trusts. A good example of this is where the API component has performed authentication and gathered role information for the customer.

If the application components need to perform fine-grained authorisation, the API component can pass customer role information as context for the request.

3.1.7. Analytics

Analytics are key to the success of an API programme. Technical analytics enable you to maintain API stability and performance, while business analytics enable you to grow your API programme.

Performance analytics enable you to ensure your APIs are meeting SLAs and other contractual obligations. Using analytics to gain insight into API usage should help in making future investment decisions. See 4. Life cycle management for more details.

To gather effective analytics, it is important for all consuming applications to have an API key in order to access the API. This allows driving out of values such as consumer location and associated peak periods, and so on.

3.1.8. State

It is important to understand where and where not to maintain state in the architecture. All effort should be made at keeping the API component completely stateless, meaning that every request to the API layer should be treated as a new request and therefore treated in the same way.

This does not prevent keeping information about the customer or the status of their request, it just means that state information is not held in the API component. This type of state information should be limited to the application or data layers.

3.1.9. API design and business process analysis

When performing the analysis required to design and develop an API, consideration should be given to all components in the reference architecture. This will ensure that the needs of all parties are met.

3.2. Categorisation of APIs

It is good practice to consider your APIs in at least 3 distinct categories to help organise your APIs for speed and agility:

• System APIs — APIs that unlock data held in legacy systems or deliver access to functions only backend systems can provide. These APIs encapsulate the complexities of interacting with legacy / backend systems
• Process APIs — APIs that create business value by breaking down silos and can be composed to work across system APIs in order to achieve a specific business purpose. These APIs are ones that automate 1 or more steps in a business process
• Experience APIs — APIs that innovate and target user experience. These APIs are commonly exposed to external consumers as part of a digital product strategy.

These 3 categories provide a way of grouping APIs based on the level of governance needed to manage changes to the APIs. Considerations include areas such as the frequency of change, effort to change, impact of change and ownership. This is shown in table 4.

3.3. Expose data as a set of resources

To identify resources, it is necessary to analyse the business domain and extract the nouns that are most relevant to business needs or, more accurately, to the needs of the application developers and customers. The API needs to be relevant and useful from the perspective of API-consuming application interactions.

Once all the nouns or resources have been identified, then the interactions with the API can be modelled as Hyper Text Transfer Protocol (HTTP) verbs against these nouns. The HTTP verbs may not map nicely, so it may be necessary to approximate.

For example, it is relatively easy to identify the nouns Customer, Address, Account and Teller as resources in a banking domain. The aim is to offer a clean Uniform Resource Locator (URL) for each thing, and each collection of things.

3.4. API publication and access

The only way an external application developer can find and use your API is if the API is published. The ability to discover an API is fundamental to API take-up and innovation, and is one of the main requirements from commercial businesses. Any published API catalogue needs to be application developer focused, as the primary point of discovery is the application developer. This means that an API must be well documented, and provide accurate and up-to-date guidance to application developer communities to encourage take-up.

Application developers need to be registered before they can develop applications that use the API. The process of registering an application against an API or API product should result in the issuance of access credentials.

Every API provider should offer a means of registration for application developers so that the consuming application base can be known and kept informed of events that impact access to APIs. All-consuming applications should be registered with appropriate credentials, as this enables API providers to understand their consuming application landscape.

Additionally, consuming applications that have been written to use an API will require a level of access relevant to that API or API resource, as follows.

• Where the API offers access to view public data, application developer registration should be automatically approved but still result in access credentials relevant to the application.
• Where the API offers access to view sensitive data, application developer registration should not be automatically approved and should instigate an agency-defined due diligence workflow and will result in access credentials relevant to the application.
• Where the API is for development / testing purposes only, registration should be self-service and the ability for an application developer to ‘try out’ the API should be provided. This is commonly known as ‘providing a sandbox’.
• Where a customer is allowed to modify data, registration will include obtaining appropriate credentials for that customer, and an internal step within the API provider to define access controls for that customer commonly referred to as authorisation.

3.5. Discovery

API catalogues will be emergent as more and more public-sector APIs are published for use. Currently, MBIE offers an established catalogue of government APIs: API Explorer — api.business.govt.nz. However, it should by no means be the exclusive location, as private sector catalogues such as Programmable Web and Mashape offer good API catalogue offerings.

When using a catalogue to identify an appropriate API, application developers are focused primarily on the resource they wish to access, rather than the government agency providing the resource. This is particularly relevant as governments and agencies change over time — the API product or resource should remain relatively stable.

The business world tends to see government as one large entity holding valuable information, and are likely to know in detail what resource they are looking for but not necessarily which agency that resource would reside within. Hence, it is important to expose APIs in terms of the resources they offer rather than the internal business process or agency structure.

The long-term aim is for discovery of APIs to be automatic and dynamic, enabling real-time integration of resources and onward presentation to customers.

4. Life cycle management

Developing and delivering APIs changes the model for most government organisations in that they are now creating and delivering products in a very similar way to a commercial entity. With that comes a need to manage, maintain and support those products throughout their life cycle in a professional way, otherwise take-up of the APIs will be limited and painful for all concerned.

The standard API life cycle follows these steps:

1. Design
2. Develop
3. Publish
4. Onboard
5. Update
6. Support
7. Retire.

Before an API goes live, in other words, is released for use, provisions should be in place to:

• support the internal development and testing of APIs
• handle release management
• support onboarding of application developers
• define the level of service the application developer (and customer) can expect from the API (SLA)
• support application developer usage of the API, including:
  • encompass life cycle / change management, handling API versioning and retirement management
  • cater for incident / events
• perform API management.

To some extent this mirrors standard service delivery practices defined in the Information Technology Infrastructure Library (ITIL),[Footnote 1] but with an API-specific flavour.

Detailed description of figure

Figure 7 is a circular flow diagram that illustrates the service life cycle management of an API. An outer circle surrounds the entire diagram and represents continual service improvement. At the centre is a circle representing service strategy. Between these 2 layers are the following 3 areas that flow from 1 to the other:

• Service design — consumer management, service level management and API design
• Service transition — internal development and testing, API catalogue, API release management and life cycle / change management
• Service operation — access management, consumer support, incident / event management and API management.

This life cycle is described in more detail in sections 4.1. to 4.4.

View larger image (PNG 109KB)

4.1. Service design

Service design covers the initial analysis and business drivers for the API as well as the way in which it will be built, where it will be hosted, and so on. Service design not only applies to the initial design of the API, but also to any changes and improvements over time.

4.1.1. Consumer management

When designing an API, it is important to inform all potential application developers as to the thinking behind the API, including the resources to be exposed, the granularity of access, and capabilities to be offered. This can include roadmaps to indicate the planned evolution of an API so that developers are pre-warned and have time to prepare for changes.

Ideally, the API services should be designed in collaboration with application developers to ensure the right product is developed to support diverse business processes across a broad set of consuming applications. It is best if API development can be performed in coordination with application developers who are producing consuming applications.

Identifying potential application developers and understanding the demand from the market can be difficult. Careful consideration should be given as to the best approach to engaging with the market and identifying your potential application developer community.

4.1.2. Service-level management

Without robust service-level management, it will be hard to engender trust in government APIs, which will negatively impact uptake.

Application developers (especially commercial entities) will need to know how long the API will exist, what commitment there is to its availability and performance, and what support is offered to those who consume the API.

Without this, API usage will be based on an untrusted model, where application developers prepare for the API being unavailable. This results in consuming applications using APIs to top up local caches of data, or to support existing batch processes, missing out on the real-time benefits of APIs.

Support could involve multiple platforms (some cloud-based, perhaps) and multiple vendors, and therefore the service levels offered in the SLA may be limited to that of the lowest common denominator.

4.1.3. API design

This incorporates the following tasks that are involved in the design of the API, prior to implementation:

• business analysis of the target audience, the business processes potential application developers are trying to implement, and how the API fits into those business processes
• Agile processes for data analysis, resource identification, software design for development of the API
• infrastructure planning, for the hosting of the API.
  Note: It is worth recognising that for application developer support, an accessible test platform is just as important as the production platform that will host the final API
• responding to requests for additions and modifications from application developers via consumer support — so service analysis does not just apply to initial design, but also to any changes.

4.2. Service transition

Service transition focuses on the implementation build of the API and deploying the API for operational use.

4.2.1. Internal development and testing

APIs need to be developed in a collaborative, flexible and adaptive way. Once the API interface specification is agreed, it is more important to get something developed, however small, and get that published for application developers than to try to build a complete API product for release.

It may well be that initial versions of the API have functionality stubbed out (resources that can be called but return canned responses) or missing, which is valid so long as the documentation indicates this. Support for this form of iterative development can be enabled through the following:

• Agile practices — Agile practices ideally suit this form of iterative development as they focus on developing small, incremental releases, ‘failing fast’ (finding out what is wrong early rather than too late) and frequent delivery of products
• Configuration management — all the components that make up an instance of the API should be held within version control, so that it is possible to rebuild a previous version, if necessary. This involves:
  • version controlling API interface specifications
  • version controlling the associated API code
  • keeping track of dependencies (for example, external libraries being used within the API code)
  • making sure access policies for individual consumers are version controlled
  • being able to provably recover all the elements of previous iterations of APIs and rebuild or redeploy if required
• Automated testing — to make the incremental release pattern efficient, it is advisable to develop automated tests in conjunction with the API code so that testing becomes an intrinsic part of the build process
• Continuous integration — tools exist that make it possible to spawn automated build, testing and subsequent deployment whenever an update of the code is placed into configuration management.

4.2.2. API catalogue

Before an API is released for application developers to access, the API’s description and interface specification should be published to an API catalogue.

The API catalogue will contain a list of all the APIs offered, along with their interface specifications and guidance on how to gain access, and use the APIs, including the granularity of access control. This information needs to be up to date and accurate in order to be relied upon by API application developers.

4.2.3. API release management

Release management is an important aspect of API transition. The aim with API development is to make small changes and release often.

The release management aspects include:

• versioning — informing application developers about the following changes:
  • where the interface specification has been changed, a major version release is required with appropriate warning to application developers, scheduled deprecation of the previous major version and support for migration to the new version
  • where backend changes that have little or no impact on the interface specification, and should have minimal impact on consumers, a minor version change release is appropriate
  • when the API changes, the interface specification must also be changed to reflect the changes. Hence, it is important to know who your application developers are
• planning API rollout — ensuring all the API artefacts are rolled out effectively and on time to the correct platforms
• emergency patches — informing application developers as to the need and schedule for emergency patch rollout, and ensuring emergency patching does not impede consuming applications.

Releases should be made to a test or development environment first.

4.2.4. Life cycle / change management

An API has its own life cycle, and it needs to be managed through the whole of its life cycle, from creation to destruction. This involves:

• monitoring performance of the API to make sure it adheres to the SLA offered (for example, availability, signs of increasing demand requiring horizontal scaling)
• monitoring usage to make sure an API, or API version, is only retired when the majority of consuming applications have migrated off it
• trimming APIs — removing capabilities that are unused, have never been used and are not likely to be used
• ensuring the API roadmap is up to date and gives a good indication of when major changes are scheduled to be made to the API.

4.3. Service operation

The service operation part of the cycle looks at the actual delivery of the services to the service levels advertised. It handles management of, and access to, the API and any underlying applications, and looks after the infrastructure that underpins it. It also includes consumer support and incident management.

4.3.1. Access management

The first interaction that service operations is likely to have with APIs is the initial act of onboarding application developers. Onboarding should provide everything the application developer needs in order to interact with the API, including access to a test environment running a representative copy of the API, underpinned by test data, documentation and preferably examples to work with.

Consideration may be needed as to whether all application developers can work with shared test data or if they need individual test data specific to their purposes.

In their day-to-day development activities application developers will want to be able to test the API without making (computationally or potentially financially) costly call outs to third party services, so it may be beneficial to provide mock versions of those APIs specifically for testing purposes.

For full system tests, however, application developers will want their applications to test the full flow including any third-party service, so an automated mechanism for that may need to be built.

Access management includes providing mechanisms through which application developers can apply for, and receive, permission and associated details to use the API. This includes external developers who want to build applications that make use of the API and applications that will ultimately be integrated with the API.

It also covers managing access to the API, including specific, fine-grained control for consuming applications. This allows operations to deploy access policies to ensure a consuming application’s access to the API is in line with agreed constraints.

4.3.2. Consumer support

Application developers will need a variety of support mechanisms to aid their use of an API, including:

• getting set up to use the API
• understanding what to use during development
• support for testing of their application in use of the API
• reporting issues with the API.

These mechanisms should include:

• telephone support
• support desk email address
• online forum / support community (see also 5.1. API components).

It could also include interactive real-time support

It is useful to include indications of the level of support so that application developers know which form of support will most rapidly address their issue — for example, 9am to 5pm telephone support, 24-hours-a-day, 7-days-a-week community forum, and response times to API failure reports.

There should also be support for handling requests for change, modifications or additions needed to the API. It should also be possible to capture and handle requests for new APIs.

4.3.3. Incident / event management

Incident and event management is geared around events picked up through monitoring, and unplanned incidents, and involves substantial amounts of communication. This includes:

• monitoring the system as a whole to identify potential issues and pre-emptively apply mitigation — for example, throttling to counter potential Denial of Service (DoS) attacks
• capturing reports of, then informing application developers of, unforeseen incidents that are currently causing a disruption of service
• informing application developers of remediation of incidents, including resolution plans and predicted completion times
• deploying temporary fixes, if necessary.

4.3.4. API management

APIs need to be managed as products, very similar to software products that commercial entities release. API management needs to be consistent across all the APIs the provider is publishing.

API management looks after availability of the API. This can involve throttling to make sure all consumers can get access to the API within the bounds of the SLA. It can also include quota management, whereby consuming applications are given limited access (for example, a set number of calls per hour) to protect the API from abuse or overuse. It should be possible to use analytics (see 4.4.1. Analytics) to assess whether throttling or quotas are needed.

For more information about capabilities to support this activity, see 5.1. API components.

4.4. Continual service improvement

It is not sufficient to release an API and let service operation keep it running. There is also a need to ensure that APIs are running optimally and can adapt to changing demand over time.

4.4.1. Analytics

Capturing and analysing data about an API in operation will pull out information useful to adapting to changes in demand. It is therefore useful to gather analytical data around:

• take-up metrics, end-user analytics such as location
• tracking API consumers, their registrations and API usage
• API performance — identifying most commonly used APIs calls so they can be made efficient
• event behaviour (for example, common patterns of behaviour)
• trace and diagnostics data.

From an API take-up / consumption perspective it is useful to capture who, where, when, how, how often, and what device type is being used. Analysis of this data can then be used to demonstrate Return on Investment (ROI).

Performance metrics are also useful, such as error rate, throughput, response time, transaction speed, backend performance, cache performance. These values can help identify trends and bottlenecks.

4.4.2. API availability

It is important not just to monitor and gather operational data about running APIs, but also to use that information to improve API offerings.

API availability is of utmost importance to API consumers, so the API providers need to monitor usage and respond dynamically to increases in demand. This requires transaction-throughput monitoring to identify potential bottlenecks or overloaded APIs and to ramp up availability to meet demand.

5. Getting started with APIs

When getting started with API development and delivery the following approach is recommended:

• Start small — pick one aspect or API product from the agency or information source and build a well-defined API.
• Work with a single application developer to ensure the interface specification meets their needs while still having relevance to broader use (for example, is not aligned solely to their business objectives).
• Have the following basic capabilities set up to support development, discovery of and access to your API:
  • an Application Developer Support Environment — developer portal tools can aid in this
  • API gateway — for ensuring safe access to your APIs
  • some means of managing published APIs — an API manager can assist in this.
• For development and hosting of the API, consider using off-the-shelf (OTS) products or software as a service (SaaS), which is subscription-based (for example, based on the number of transactions) to reduce maintenance and support costs. Subscription-based offerings allow an agency to start with a small number of transactions and increase these over time as their API ecosystem grows.
• Use analytics to gain visibility of take-up, developer engagement and usage profiles, and adapt APIs to meet changing needs over time.

5.1. API components

The following are definitions of components that provide API development support capabilities.

Detailed description of figure

Figure 8 illustrates a general API architecture that includes the core components and capabilities of an API. In general, the diagram shows:

• consuming application developers discover and subscribe to APIs through the API developer portal. They then create applications (for example, web, mobile and server apps) that sit on devices. 
• customers use consuming applications on devices (for example, desktop browsers, mobiles and web servers) to access an API from the API gateway. 
• Identity Federation Services provides authentication and Single Sign-On (SSO) services to customers and secure transportation of authentication and authorisation information.
• the API gateway hosts the API after it is published by the API manager
• internal API developers and application developers expose and create APIs through the API developer portal, API manager and API gateway.

The main components and capabilities are described in more detail in sections 5.1.1. to 5.1.3.

View larger image (PNG 150KB)

5.1.1. API developer portal

Agencies developing APIs need to be able to engage, onboard, educate and manage consuming application developers, whether inside or outside the organisation. These management activities will generally include registration, documentation, analytics and so on.

The easiest way of making these capabilities available to application developers is to offer a dedicated website or a development portal, which should offer:

• discovery — making it simple for developers to find APIs that match their need
• onboarding — allowing developers to register and sign-up for API usage plans with support for automatic approval or manual approval workflows
• education — providing developers with the information they need to make use of APIs
• examples — offering example code and sample applications to illustrate the functionality of the API
• API evaluation — giving developers a ‘sandpit’ capability to try the APIs interactively
• community — enabling developers to share knowledge, experience and best practices via a support community such as online forums
• metrics — delivering insight into API usage and performance that could be useful to developers
• SLAs — a place to publish API SLAs, defining performance, availability metrics.

5.1.2. API gateway

The API gateway is the means through which APIs are offered to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an agency with the ability to control who has access to their APIs by enforcing policies for access control.

The gateway is sometimes referred to as the API policy enforcement point. Some API gateways also offer additional capabilities such as:

• security — offering authentication and authorisation services. Using threat protection capability to protect backend systems against common vector attacks such as SQL injection, Cross Site Scripting and Cross Site Forgery. The API gateway is essentially the Policy Enforcement Point (PEP)
• performance — maximising API efficiency to support consuming applications and minimising downtime
• data transformation — converting transiting data into application-friendly formats
• orchestration — composing new, aggregate APIs from multiple existing APIs
• quality of service (QoS) — provides QoS for consuming applications and enables an agency to apply policies for a specific consuming application or policies that protect backend systems from overload. This is commonly referred to as ‘throttling’ and ‘quota’
• logging — saving events as messages in a file or database for later analysis and auditing.

5.1.3. API manager

The API manager is a technical layer enabling an agency to control an API’s visibility and behaviour. It is usually exposed as a UI or console to internal staff only, as it is seen as an administration component. It offers:

• access control — API manager is the place where API administrators can control API access such as defining access policy for the API gateway to enforce, disabling an API key or other credential that is being used maliciously
• QoS policy definition — administrators use the API management layer to define QoS policies such as defining quota limits for an application or API
• API registration — administrators register APIs in the API manager so that they can be exposed to application developers. API developer portals generally communicate with an API management layer to obtain information about exposed APIs and to push application developer details. As part of the release process, API administrators register APIs in a management layer
• API catalogue administration — providing governance over the API catalogue, what is exposed and what is not, what is available for external use or for internal use only
• life cycle management — managing the full life cycle of APIs from initial publication to destruction.

The main capabilities usually support:

• planning and design
• implementation
• basic and advanced deployment and running
• versioning and retirement
• allowing policies to be applied to individual APIs
• helping to onboard consuming applications.

6. API governance

This version of the API guidelines does not yet offer detailed guidance on API governance. See section 2. API governance in Part C: API development 2022.

7. Glossary of terms

Analytics

Analytics in the context of these guidelines is the capturing and reporting of API usage.

API (Application Programming Interface)

An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another.

API catalogue

The API delivery component that lists the APIs offered, along with their interface specification and guidance on how to gain access and use the APIs.

API developer

The organisation (or person) who creates the API and maintains the interface specification for the API. An API developer creates and documents an agency’s APIs. API developers generally have a good understanding of an agency’s function.

API developer portal

The API delivery component that allows API providers to engage with, onboard, educate and manage application developers whether inside or outside the organisation. These management activities will generally include registration, documentation, analytics and so on.

API gateway

The API delivery component that allows API providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an API provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities.

API manager

The API delivery component that allows API providers to control an API’s visibility and behaviour. It is usually exposed as a UI / console to internal staff only, as it is seen as an administration component. It offers a variety of capabilities, including API registration and catalogue administration.

API provider

The organisation that provides the API to expose a resource (information or functionality) for consumers.

Application

The software behind the API that provides the business logic for the resource.

Application developer

Software developer or organisation that builds consuming applications that use the API. An application developer needs to be able to discover, understand and access your APIs. They can be internal to your agency, developers that work with trusted partners, developers from other agencies or developers from the private sector.

Consumers

Customers, consuming applications and application developers who use the API.

Consuming application

Any application (on any device) that consumes or uses an API.

Context

Context in these guidelines generally refers to request context. For example, a JWT (JSON WebToken) may contain information about the customer initiating an API request.

Customers

People (or organisations) that use the consuming applications to access the API resources the API provider is offering.

Discovery

The ability for application developers to find resources and associated APIs to use in their consuming applications.

Interface specification

Provides technical information to the application developer community about the API. It includes information about how the API works, any access control features and any error conditions.

Product manager

The product manager is usually a technical role. They understand an agencies API landscape and are owners of API management platforms.

Product owner

The product ownership function usually resides in a business area rather than technology. The role of the product owner is to understand the product that the agency is trying to deliver, shape and communicate the vision and delivery schedule for the product, represent the stakeholder and customer perspective, and to make decisions on the representation of the product in an API.

Publish

The act of releasing the interface specification and associated API to a location accessible by application developers.

Resource

The information or functionality exposed by the API.

State

State defines the point in time record of an in-flight transaction. Some systems maintain ‘user state’ for a period of time to enable a transaction to be continued from the point of last recorded state. APIs are usually, but not always, considered stateless.

8. Glossary of acronyms

API

Application Programming Interface

COTS

Commercial off-the-shelf

DoS

Denial of Service

EU

European Union

FSD

Federated Service Delivery

GDPR

General Data Protection Regulation

GP

General Practitioner

GST

Goods and services tax

HTTP

Hyper Text Transfer Protocol

ITIL

Information Technology Infrastructure Library

JWT

JSON Web Token

MBIE

Ministry of Business, Innovation and Employment

MoH

Ministry of Health

MOU

Memorandum of Understanding

MPI

Ministry for Primary Industries

NGOS

Non-governmental organisations

NZBN

New Zealand Business Number

OWASP

Open Web Application Security Project

PMS

Practice Management System

QoS

Quality of Service

REST

Representative State Transfer

ROI

Return on Investment

SDK

Software Development Kit

SLA

Service Level Agreement

SQL

Structured Query Language

SSO

Single Sign-On

UI

User interface

URL

Uniform Resource Locator