1.3.Scope and Application

1.3.Scope and Application

large colour icon watermark cropped

1

API Standard

CONTENTS

1.CONTEXT

1.1.Background

1.2.Purpose

1.3.Scope and application

1.4.Policy context

1.4.1APIs

1.4.2Geospatial APIs and web services

1.5.The ICT Services Catalogue

2.KEY PRINCIPLES

3.REQUIREMENTS

3.1.Standard elements

3.1.1Roles

3.2.Service level and complexity

3.3.Requirements tables

3.3.1 Silver (standard) – Use Cases / Scenarios

3.3.2 Gold (complex) – Use Cases / Scenarios

3.4.Elements of this standard

3.4.1General requirements

3.4.2API Authoring

3.4.3API Management

3.4.4Mobile

3.4.5Developer Portal

3.4.6Service Management

3.4.7Open APIs

3.4.8Additional aspects

DOCUMENT CONTROL

APPENDIX A – DEFINITIONS

APPENDIX B – ABBREVIATIONS

APPENDIX C – RELATED DOCUMENTS

APPENDIX D – STANDARDS

Developing technical standards

Management and implementation

  1. CONTEXT

1.1.Background

This is a technical standard developed bythe NSW ICT Procurement and Technical Standards Working Group. The standard contains technical and functional requirements that agencies should consider when commissioning ICT services forApplication Programming Interface (API)solutions.

By defining the necessary and common elements across agencies, the standard provides an opportunity to leverage the buying power of Government as a whole,improve procurement efficiency and increase interoperability.

The NSW Government position is that APIs should be commissioned (delivered ‘as a Service’; developed in-house or by a third party etc) ‘open by default’ that is they are available for the widest possible use with minimum restrictions on their use and/or reuse.

1.2.Purpose

The purpose of this standard is to assist NSW Government agencies to develop, procure and implement APIsolutions and tools, as well as take full advantage of their benefits. This standard also helps agencies procure in a strategic manner that reflects the NSW Government’s priorities as outlined in the NSW Government ICT Strategy.

This standard details the issues that need to be considered so each agency can identify the available options that best suit their business requirements, helping agencies achieve value for money through cost savings and improved flexibility of service offerings.

1.3.Scope and application

This standard applies to all NSW Government departments, statutory bodies and shared service providers. It does not apply to state-ownedcorporations, but is recommended for their adoption.

For the purposes of this standard, APImeans: the defined interfacethrough which interactions happen between a web client and a resource. The API itself has no intrinsic value, however, the value is through the backend data and application functionality the interface enables.

For the purpose of this standard, API Management Solution means the governance engine, tools and resources to enable and protect APIs.

For the purpose of this standard, API Developer Portalmeans the website where developers can find, review and register for APIs.

This standardsets out service definitions as minimum requirements that vendors must meet to be able to offer their services through the NSW ICT Services Catalogue. Agencies should consider any specific operational or regulatory factors that impact their requirements, and specific requirements they have in addition to those detailed in this standard.

1.4.Policy context

The NSW Government ICT Strategy and Digital+ 2015 Final Updateset out the Government’s plan to: build capability across the NSW public sector to deliver better, more customer-focused services that are available anywhere, anytime; and to derive increased value from the Government’s annual investment in ICT.

Information sharing, open data and reuse of technology are priority initiatives of the ICT Strategy, to maximise the return on government investments, support better policy development and service delivery. The NSW Government ICT Investment Policy and Guidelines establishes these requirements for all new ICT projects, particular to make better use of the functionality in existing systems. APIs are an essential mechanism for meeting these requirements.

The NSW Government Enterprise Architecture(NSW GEA) provides direction and practical guidance to accelerate the development of agency EA capability and enabling a common, intra and inter agency approach to the design of digital government. It encompasses all aspects of enterprise architecture activity at the business, information, application and technology infrastructure layers. The NSW GEA is mapping the landscape of Whole of Government systems available across the sector, highlighting opportunities for reuse and where APIs can add value.

NSW Government, along with many governments in other jurisdictions, has moved towards opening up previously protected databases and applications, so that data and functionality can be accessed across agency boundaries or reused in new systems. Within NSW this has been reflected in the development of the NSW Government Open Data Policy, which provides clear direction for agencies to make their data available to the public in machine readable forms, including through the availability of APIs.

Developing whole of NSW Government ICT technical standards is a key initiative of the NSW Government ICT Strategy, driven by the ICT Procurement and Technical Standards Working Group. These standards leverage principles defined in the NSW Government ICT Strategy and the NSW Government Cloud Policy, and they support the NSW ICT Services Catalogue.

The standards set out service definitions as minimum requirements that vendors must meet to be able to offer their services through the NSW Services Catalogue. This helps achieve consistency across service offerings, emphasising a move to as a service sourcing strategies in line with the NSW Government ICT Strategy, and it signals government procurement priorities to industry.

This standard should be applied along with existing NSW Government policies and guidance, including the NSW Digital Information Security Policy. More information on the process for the development of standards that populate the ICT Services Catalogue is at Appendix D – Standards.

1.4.1APIs

APIs provide a software to software interface so that two applications can communicate directly without any user intervention. They can:

  • enable one application to leverage the functionality of another application
  • enable one application to access or manipulate the data held or processed by another application.

APIs enable agencies to efficiently share and publish data in the mose usable forms and to reuse existing technolgoy for a variety of purposes.

Open APIs further increase the opportunities for sharing and reuse by government, the developer communitiy and the broader public – through publication, documentation, accessibility and licensing.

A market trend first emerged in the form of service orientated architecture (SOA), which has now moved mainstream with the explosion of web-orientated APIs to support the digitial economy and the use of mobile devices for all manner of interactions.

APIs and the appropriate Service Management approach (as defined in this standard) aligns itself with Hypertext Transfer Protocol (HTTP) request messages and structured response messages (see Appendix A – Definitions for details of terms used).Although the trend is towards a REST style API rather than SOAP, the use of either would be a mandatory requirement from a supplier of an API Management Solution.

1.4.2Geospatial APIs and web services

APIs that enable geoprocessing technologies to interoperate, or provide access to spatial information and services must indicate whether or not they can demonstrate compliance with Open Geospatial Consortium (OGC) implementation standards.

For further information, refer to the NSW Government Guidelines for Publishing Spatial Web Services and the OGC website .

1.5.The ICT Services Catalogue

TheICT Services Catalogue provides suppliers with a showcase for their products and services, and an opportunity to outline how their offerings meet or exceed standard government requirements. The standards, together with supplier service offerings, help to reduce red tape and duplication of effort by allowing suppliers to submit service details only once against the standards. The offerings are then available to all potential buyers, simplifying procurement processes for government agencies.

Implementing this category management approach will embed commonapproaches, technologies and systems to maintain currency, improve interoperability and provide better value ICT investment across NSW Government.

  1. KEY PRINCIPLES

The following key principles underpin this standard:

  • Interoperability: Meeting this standard will help agencies design, implement and manage APIs in a manner that allows the reuse of existing private or public APIs and tools from others.
  • Fit for purpose: API standards should meet agency business requirements, and provide sufficient bandwidth for current and future applications.
  • Information security: Meet any applicable requirements of the NSW Digital Information Security Policy and ISO 27001.
  • Omni channel: The use of APIs and appropriate management solutions is not limited to one specific use case. Generically APIs can be consumed across multiple channels. They should be mobile capable by default, but also able to be consumed via the web, department to department, department to citizen, etc.
  • Leveraging: The design and management of APIs will leverage government standards in identity management, authentication and authorisation, data sources, citizen and agency portals, encryption and other security principles.
  • Value for money: API development should deliver value for money, in line with the investment principles set out in the NSW Government ICT Investment Policy and Guidelines.
  1. REQUIREMENTS

3.1.Standard elements

When considering API solutions an agencyneed to consider the Service Management aspects of the service(s) on offer. In this respect the term “API Management Solution” is commonly used to describe this aspect.

To implement and manage APIs there are standard elements common toall types of implementations, as set outbelow:

3.1.1Roles

Management Layer

  • Product Owner
  • Owns the API, accountable for policy application and maintenance.
  • Responsible for defining Service Level Agreements.
  • Business/Systems Analyst
  • Responsible for eliciting requirements from business and documenting.
  • IT Architect
  • Working with and from the requirements to design a final system.
  • System Maintenance and Support
  • Testing delivered system, providing ongoing support.
  • Reviewing analytics and providing reports on platform to product owner.

API Authoring Layer

  • Development / Vendor (API Creation)
  • Realizing the architectural design that meets the product requirements.
  • Policy Author
  • Implementing the Service Level Agreement, through policy, in alignment with the product requirements and Developer needs.
  • Internal Developer / Vendor (API Consumption)
  • Uses the API to provide 3rd Party services to the users.

Consumer Layer

  • External Developer / Vendor (API Consumption)
  • Uses the API for own or others use.
  • End User
  • Consumer of 3rd party services
  • Public
  • Government (Private)
  • Business (Private)

3.2.Service level and complexity

The following API requirements and use case tables are separated into two service levels–silver and gold, reflecting the complexity of the APIsolution required:

NSW Government API Use Cases:

  1. Internal: This use case is designed to meet the move towards API development and exposure for internal department use. An example would be to expose a dataset from an existing data-store or application via an API (whether REST or SOAP). This API can then be consumed by another internal application or service via that API, rather than through a client/server communication or agent to agent-based communication.
  1. Unregistered – No SLA: This use case is designed to support the broader NSW Government push towards open data where public information is made available in a common and mobile supported format. A user is not required to register or log in to access the underlying system. An example would be to expose names of Secretaries of each NSW Government department via the API, this would expose their name, public profile, department informationetc. It would be expected that this information would already be publicly available via other means but could now be consumed by interested parties via the API. It is not expected that this would require a SLA behind it, this would be an appropriate service withappropriate environments to support it. There would be basic data integrity protection through malware affordances but this use case would not require high levels of confidentiality or high levels of availability. Should expectations on these types of services increase, they should be elevated to a higher level described below.
  1. Unregistered – with SLA: This use case is designed to support both Open Data by NSW Government and to deliver a committed service to its constituents across new channels such as APIs and mobile. A user is not required to register or log in to access the underlying system but there is a higher degree of service support, data quality and availability expected. An example would be to expose the NSW Transport bus and train timetable, service outages, live running times, positional information, calculated shortest route, etc. through an API for consumption by any interested party. It is expected that this data is publicly available by other means, but it is also expected that if an organisation wants to consume this data then there would be a SLA afforded against it. This means that the service would be supported by high levels of availability and integrity. As this is public information then confidentiality is less important.
  1. Registered: This use case is designed to support all of the above use cases where confidentiality is required on the data or service being exposed, and when the department wishes to maintain a relationship with the developer creating apps or software to consume data or functionality through the API.A user is required to register or log in to access the underlying system. Privacy, security and the sensitivity of the data are important considerations.
  • This could be for sharing of information via an API across department, local, state or federal boundaries where specific security principles need to be enforced.
  • This could allow the mobile number of an individual to be retrieved.

The two service levels are:

Silver:StandardAPI.

Gold: Advanced/complex API.

3.3.Requirements tables

The tables set out the recommended business and technical requirements for NSW Government. They provide a consistent approach for all NSW Government agencies regardless of their size. Explanations for each element of the following use cases are providedat section 3.3.

When reviewing the table, the characters used denote the following.

 / Required
 / Optional, but beneficial

A brief description of each requirement is provided after the tables.

1

API Standard

3.3.1 Silver (standard) – Use Cases / Scenarios

‘Use cases’ for API that are anticipated in agencies are included in the table below. The corresponding requirement sections of this standard are markedin the columns.

Use Case / Scenario
Silver / API Authoring / API Management
Common tool integration / Debugging / GUI based authoring / Role based access / Script based authoring / Auditing logging / High availability / Lifecycle management / Malware protection / Orchestration / Performance / Representation/transformation / Reporting/analytics / Security / Source code repository
Internal /  /  /  /  /  / 
Unregistered – NoSLA /  /  /  /  /  /  /  / 
Unregistered – SLA /  /  /  /  /  /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  /  /  /  /  / 
Use Case / Scenario
Silver / Mobile / Developer Portal
Application analytics / Device feature invocation / IoT capable protocols / Secure container / Session sharing / SDK – common mobile platforms / Single sign on / API keys / Discussion, notification / Documentation / Monetisation / Process workflows / Personalisation – CMS / Self service
Internal /  /  /  /  /  / 
Unregistered – NoSLA /  /  / 
Unregistered – SLA /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  /  /  /  /  /  / 
Use Case / Scenario
Silver / Service Management / Open APIs
Self-service administration / Full-service administration / Any compliant data centre / NSW Government Data Centre / Onshore/offshore management / Service level management / Multi-service broker provision / Service level management / Discoverable / Documented / Accessible / Reusable
Internal /  /  /  / 
Unregistered – No SLA /  /  /  /  /  / 
Unregistered – SLA /  /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  / 

3.3.2 Gold (complex) – Use Cases / Scenarios

‘Use cases’ for API that are anticipated in agencies are included in the table below. The corresponding requirement sections of this standard are ticked in the columns.

Use Case / Scenario
Gold / API Authoring / API Management
Common tool integration / Debugging / GUI based authoring / Role based access / Script based authoring / Auditing logging / High availability / Lifecycle management / Malware protection / Orchestration / Performance / Representation/transformation / Reporting/analytics / Security / Source code repository
Internal /  /  /  /  /  /  /  /  /  /  /  / 
Unregistered – No SLA /  /  /  /  /  /  /  /  /  /  /  / 
Unregistered – SLA /  /  /  /  /  /  /  /  /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  /  /  /  /  /  /  / 
Use Case / Scenario
Gold / Mobile / Developer Portal
Application analytics / Device feature invocation / IoT capable protocols / Secure container / Session sharing / SDK – common mobile platforms / Single sign on / API keys / Discussion, notification / Documentation / Monetisation / Process workflows / Personalisation – CMS / Self service
Internal /  /  /  /  /  / 
Unregistered – No SLA /  /  /  /  /  / 
Unregistered – SLA /  /  /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  /  /  /  /  /  / 
Use Case / Scenario
Gold / Service Management / Open APIs
Self-service administration / Full-service administration / Any compliant data centre / NSW Government Data Centre / Onshore/offshore management / Service level management / Multi-service broker provision / Service level management / Discoverable / Documented / Accessible / Reusable
Internal /  /  /  / 
Unregistered – No SLA /  /  /  /  /  / 
Unregistered – SLA /  /  /  /  /  /  /  / 
Registered /  /  /  /  /  /  /  /  /  / 

1

Top View