API Standard

CONTENTS

2 API Standard

1. CONTEXT

1.1. Background This is a technical standard developed by the NSW ICT Procurement and Technical Standards Working Group. The standard contains technical and functional requirements that agencies should consider when commissioning ICT services for Application 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 API solutions 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-owned corporations, but is recommended for their adoption. For the purposes of this standard, API means: the defined interface through 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 Portal means the website where developers can find, review and register for APIs. This standard sets 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 Update set 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

3 API Standard 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

4 API Standard

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.2 Geospatial 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 http://www.opengeospatial.org/docs/is .

1.5. The ICT Services Catalogue The ICT 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 common approaches, technologies and systems to maintain currency, improve interoperability and provide better value ICT investment across NSW Government.

2. 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.

5 API Standard

3. REQUIREMENTS

3.1. Standard elements When considering API solutions an agency need 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 to all types of implementations, as set out below:

3.1.1 Roles Management Layer

 Product Owner

o Owns the API, accountable for policy application and maintenance. o Responsible for defining Service Level Agreements.

 Business/Systems Analyst

o Responsible for eliciting requirements from business and documenting.

 IT Architect

o Working with and from the requirements to design a final system.

 System Maintenance and Support

o Testing delivered system, providing ongoing support. o Reviewing analytics and providing reports on platform to product owner.

API Authoring Layer

6 API Standard

 Development / Vendor (API Creation)

o Realizing the architectural design that meets the product requirements.

 Policy Author

o Implementing the Service Level Agreement, through policy, in alignment with the product requirements and Developer needs.

 Internal Developer / Vendor (API Consumption) o Uses the API to provide 3rd Party services to the users. o

Consumer Layer

 External Developer / Vendor (API Consumption)

o Uses the API for own or others use.

 End User

o 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 API solution 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.

2. 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 information etc. 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 with appropriate 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.

7 API Standard

3. 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.

4. 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: Standard API. 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 provided at 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.

8 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 marked in the columns.

API Authoring API Management S L R o G if M e u U e a p r I c l O o c b y w r r e Use a c a c Rol ti c Case / s l r h e n o Scenar De e e e e Represe ba g Se d io bu d m p s ntation/ Common tool integration se High availability / cur e ggi a a r t transfor Silver d a ity r ng u n o r mation acc n e t a t a ess a p h g e ti l o o e c o y si ri m ti n ti t n e o c o g n n s r t y Intern al     Unregi stered – No       SLA Unregi stered          – SLA Regist ered            9 API Standard

Mobile Developer Portal D e v I A i o p c T p SD e c D li K – f a o M c co e p Dis c o Pe a Se m Pr a a cu u n rso ti cur mo oc Sel Use Case / Scenario t b Sessi Singl AP ssi m e nal o e n ess f Silver u l on e I on, e ti isa n co mo wo ser r e shari sign ke no n s tio a nt bil rkf vic e p ng on ys tifi t a n – n ain e lo e i r cat a ti C a er pla ws n o ion ti o MS l tfo v t o n y rm o o n ti s c c c a o s ti ls o n Internal      

10 API Standard

Unregistered – No SLA    Unregistered – SLA        Registered              

Service Open APIs Manage ment A Discove Documented Acce Reus n rable ssibl able y e c o NS m Ser W p vic Mult Use Go Onsh li e i- Case / ver ore/ Self- a lev servi Scenario nm offsh service n el ce Silver Full-service administration ent ore adminis t ma brok Dat man tration d na er a age a ge provi Ce ment t me sion ntr a nt e c e n tr e Internal     Unregiste     red – No   SLA Unregiste     red – SLA     11 API Standard Registere    d     

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.

API Management API Authoring R e R pr o es l Lif M e So GU e ec Use al nt ur I b ycl Case / w Or at ce ba a e Scenari ar ch io Se co Deb se s m o e es n Reporting/a cu de Common tool integration uggi d e High availability an pr tra /t nalytics rit re Gold ng au d ag ot tio ra y po th a e ec n n sit ori c m tio sf or ng c en n or y e t m s at s io n Internal           Unregis tered –           No SLA Unregis tered –             SLA Registe red             12 API Standard

Mobile Developer Portal

Dis Ap Pr cu Do plic M oc Pers Sel Use Case / Scenario ssi cu atio on ess onali f Gold IoT capable SDK – common on, me n API keys eti wo satio ser protocols mobile platforms no nt ana sat rkf n – vic tifi ati lyti ion lo CMS e cat on cs ws ion

Internal     Unregistered – No SLA       Unregistered – SLA          Registered          

Service Management Open APIs

13 API Standard

F Servi Disc D Accessi Reusab u A ce over o ble le ll n level able c - y man u s c age m e o men e NS r m t n W v p t Go Mult i li e ver i- c a d Use Case nm servi e n / en Service level ce Self-service administration a t t management brok Scenario d d Da er Gold m a ta prov i t Ce ision n a ntr is c e t e r n a t ti r o e n Internal     Unregist     ered –   No SLA Unregist     ered –     SLA Registere     d      

14 API Standard

3.4. Elements of this standard

3.4.1 General requirements Commissioning services Services that assist the customer in transitioning to the as a service environment. For the purposes of this standard, commissioning services will include design services – ensuring the service is designed to deliver the required outcomes; commissioning services – ensuring the service is commissioned in accordance with the design and customer requirements; transition services – ensuring services are transitioned to the service from their existing environment(s). Any response to a market engagement should provide a complete list of commissioning services that a customer can take advantage of. Management tools for APIs The service will have appropriate management tools that allow management of the APIs. Any response to a market engagement should provide details of the tools used (or available including any recommendations), whether the tools are available to the customer, and to what extent the customer is able to self-manage APIs. The management tools will also provide inputs for service reporting requirements.

3.4.2 API Authoring To build an API for use there are various aspects that are common across vendor solutions that meet or surpass the requirements. These items provide a basic understanding of each: Common tool integration When developing an API the API author will utilise tools of preference and may use tools they are familiar with to perform testing, debugging, scripting, etc. It is expected that any API solution should offer integration and support for a variety of public tools and open source artefacts. APIs should be developed with the concept of consistency for requests and responses (including error reporting) with the aim of minimising integration of future services. Debugging The use of debugging is a common step in building an API, the toolset must provide levels of debugging in relation to the complexity of the use case. GUI based authoring When authoring an API the simplicity of use will result in rapid creation and deployment of the API. Role based access The use of role based access for API authors, solution and enterprise architects is determined by each use case. Script based authoring The ability to author APIs through the use of scripts can meet the demands of more complex and frequent deployments.

3.4.3 API Management Auditing logging The ability to capture audit and logging information, this may be within the solution or external.

High availability The capability to provide maximum uptime through high availability methods, this can be include clustering, active/active deployments, etc.

15 API Standard

Lifecycle management The full capability of lifecycle management including API development, release, versioning, automation, deprecation, product management, etc. Malware protection As the run-time component for APIs can be internet facing then full message protection and content inspection may be required. This includes malware protection, anti-virus, message inspection and limiting. Orchestration The ability to provide loose coupling across APIs and relevant services ensures greater flexibility when delivering complex API services. Performance Large transaction volumes through APIs demand appropriate performance capability and efficiency, including caching, scale out, scale up, load balancing, etc. Representation/transformation An API connects backend data to front end client; the need for appropriate representation of data sets for consumption and the ability to transform protocols and message types is required. Reporting/analytics Historical reporting through to real time analytics encompass both ends of the reporting features, the extent of the reporting and analytic capability is determined by the needs of the department and use case. Security This includes integration with various protocols, authentication, authorisation, security architectures, message encryption, API obfuscation, conformance to standards, etc. Source code repository Integration with open source or vendor specific source code repositories to allow the integration of development artefacts into the API lifecycle. By default NSW Government commissioned APIs should be ‘open’ and available for subscriber services. APIs that are not open must be clearly defined and reported as such.

3.4.4 Mobile Application analytics Provide insight into the operation and usage of mobile applications and functions within mobile applications. Device feature invocation Consume device features and platform capabilities, this could include push notifications, Touch ID usage, geolocation tracking, manufacturer features (IE Samsung Knox, IOS Keychain). IoT capable protocols Provide features and capability to support Internet of Things connectivity, this could include support for XMPP, Websockets, MQTT, AMQP.

Secure container

16 API Standard

Provide features specific for mobile applications and data residing on the mobile device within a secure container, this is predominantly tied to BYOD use cases and can now involve API consumption and mobile data storage needs. Session sharing Provide secure session sharing across devices using technologies such as BLE, NFC, QR code. As an example this would allow an authenticated user to transfer their active session from one mobile device to another. SDK – common mobile platforms Provide support for application, device, user management and control that is deployed with applications for common mobile platforms. The SDK will provide easy to consume code to allow consumption of APIs within the API Management environment. Single sign on Provide secure capabilities for users who have authenticated at the device to have those credentials or access tokens reused for sign on to other applications on the device.

3.4.5 Developer Portal API keys The ability to provide a basic level of access and control to the API by registering applications and developers against an API with the key. Discussion, notification The ability to engage with users of the API through forums, email notification, feedback, etc. Documentation The ability to easily document the APIs through self-documenting features of APIs and description languages. Monetisation The ability to sign up organisations and developers and charge per usage or otherwise for access to the APIs. Process workflows The ability to control organisation and developer registration, approvals, deactivation, etc. through a suitable workflow engine. Personalisation – Content Management System (CMS) The ability to tailor the look and feel of the developer portal to suit individual requirements. Self service The ability to allow developers to view APIs, register themselves or organisation, use the APIs through simple self-service means.

3.4.6Service Management Self-service administration The ability to automatically provision and de-provision for all agency resources within the system, together with other appropriate administration and management tasks that can be delegated from the service provider that do not impinge on the solution being provided to other customers.

Full-service administration

17 API Standard

All provisioning, de-provisioning, together with all other administration and management tasks required to operate the environment, are provided as part of the service offering. The only exception will be Service Management of the provider which remains the sole responsibility of the initiating agency. Cloud compliant hosting facility All relevant cloud services for the solution may be provisioned from a compliant hosting facility. Compliant hosting is defined as having the following attributes and/or capabilities:  The location of the hosting facility must be identified either by name and/or location (city and country) in any response  The hosting location cannot be changed without first informing the agency concerned  The service provider undertakes, maintains and provides access to SSAE 16 Service Organization Control (SOC) Type II reports (or equivalent) for the services and facilities in scope for the engagement  The hosting facility must comply with minimum Tier 3, as defined by the Uptime Institute, ANSI TIA-942, or an equivalent industry standard.  The hosting facility must be certified against ISO 27001; compliance with the following international standards is desirable: o ISO 9001 o ISO 27002 o ISO 20000-1:2011 o ISO 14001 Other desirable certifications may include, but are not limited to: o PCI-DSS v3.0 or later o Australian Signals Directorate o ASIO-T4 o Uptime Institute o CSA Also consider contractual obligations relating to the service provider allowing security assessments and treatment of outcomes as agreed with the client. If the hosting facilities changes to a location that is deemed unacceptable either to NSW Government or to the agency and/or loses attributes and/or capabilities identified above, the agency may need to consider termination of services. NSW Government Data Centre All relevant services for the solution may be provisioned from one or both NSW Government Data Centres (GovDC). Depending on the service offering and agency requirements, it may be possible to ‘burst’ some elements of services to other location(s) subject to agreement with the commissioning agency. Burst data centres must be deemed ‘compliant’. If the ‘burst’ data centre facilities change to a location that is deemed unacceptable either to NSW Government or to the agency, the agency may need to re-examine the ‘burst’ service or the full service. Onshore/offshore management All solution providers must be able to articulate where their services will be provided from, including any remote support services. For example, with a ‘follow the sun’ support model, the locations of each of their support sites around the globe need to be identified. Any changes to 18 API Standard these need to be communicated to the customer agency promptly and if this causes issues, the agency has the right to cancel the service with appropriate notification. Multi-service broker provision Any solution provider must work within the confines of a multi-service provider environment where either the agency or nominated provider will perform broker service provision. This will be defined as one provider being made accountable for the provision of all associated services, whether these are provided by the provider itself, or other third-party providers. Service level management Agencies will retain ultimate responsibility for service level management in any solutions engagement, which would ordinarily be covered by a SLA. Agencies, service-brokers and solution providers need to agree all SLA reporting and other related activities as part of any transition-in process.

3.4.7Open APIs Discoverable The existence of each exposed API must be published on publicly available resources. Documented Each exposed API must have freely accessible documentation that has sufficient information that would enable a competent developer has to make use of the API without further information. Free registration to access the API documentation is acceptable. Access to Open APIs or related documentation should not be subject to any Non-Disclosure Agreement (NDA). Accessible Each exposed API should be accessible free of charge to enable testing. Where access to the API is chargeable and/or access is identified, developers must have non chargeable access to test APIs. Where access to the live API is not possible (e.g. chargeable usage applies, service level agreements are in place, or the API returns sensitive data) a test environment will be provided to allow potential users to experiment and test the API. Reusable Licences for usage of Open APIs by a consuming system with anonymous access must be royalty free, perpetual, non-exclusive and transferable. Open APIs should apply the Creative Commons licensing framework to manage attribution, re-use and derived works https://creativecommons.org/licenses/ Open APIs may make use of shared API models through API Commons http://www.programmableweb.com/news/api-commons-launched-share-your-api- code/interview/2013/11/05

3.4.8Additional aspects There are numerous other common aspects of APIs that should be considered based upon the use case desired. The following definitions used in an API architecture are briefly described and have been considered in the previous tables:

 End Users o The consumer of the information provided by the API. o User Experience.  Client applications o The application or web client that makes the HTTP(S) call to the API. o Mobile SSO, SDK. 19 API Standard

 Security o Authentication, authorisation, encryption, obfuscation, content inspection, malware protection, etc.  Performance o Caching, message size control, rate limiting, scale out, scale up, prioritisation, throttling, shaping, etc.  Data Formats o XML, JSON, CSV Protocols o HTTP, HTTPS, FTP, SFTP, etc.  Transformation o XML to JSON, JSON to XML  Mediation o SOAP to REST, REST to SOAP, HTTPS to HTTP  Orchestration o Aggregate multiple backend APIs to create a composite API.  Access Control o SAML, LDAP, OAuth, OpenID.  Deployment o High availability, clustering, cloud, virtual, physical, run time engine  Development o lifecycle, dev-test-staging-prod, versioning.  Analysis o auditing, logging, reporting, analytics  Backend system o The source of record that is exposed through the API.

20 API Standard

DOCUMENT CONTROL Document history Status: Released Version: 1.0 Approved by: Executive Director, Strategic Policy Approved on: 18 December 2015 Issued by: ICT Services, Services & Digital Innovation Division, Department of Finance, Services & Innovation (DFSI) Contact: ICT Services, Services & Digital Innovation Division, Department of Finance, Services & Innovation (DFSI) Email: [email protected] Telephone: (02) 9372 7445 Review This standard will be reviewed as required.

21 API Standard

APPENDIX A – DEFINITIONS

Term Definition

AJAX Asynchronous JavaScript and XML is a group of web development technologies, which is used on the client-side to create asynchronous web applications. API (Application APIs enable software to interact with other software through exposed Programming Interface) functionality. An API is independent of communication protocols and message formats. API Description Language A set of formal languages designed to provide a structured description of a RESTful API that is useful both to a human and for automated machine processing. Examples include WADL, Swagger, RAML, API- Blueprint. API Key An authentication or authorization code passed in to an API request via a header or parameter to identify the requester. API keys are used to track and control how the API is being used, for example to prevent malicious use or abuse of the API (as defined perhaps by terms of service agreements). Authentication Identifying the user of the API. Common techniques for authentication include API keys and OAuth. Authorisation Authorisation is the function of specifying access rights to resources related to information security and computer security in general and to access control in particular. Cache A collection of responses that are reused by the client to improve performance. Client The client is the initiating party that sends an API request. Often times there will be many clients consuming the same API, e.g. web, machine, mobile. Collection An API resource that groups other resources together.

DELETE (HTTP Method) The HTTP method for deleting resources with a RESTful API.

Endpoint The URI that goes after the base URL and points towards the requested API functionality or resource. Gateway A proxy that translates (mediation) between protocols. Often gateways will provide additional functionality such as security, reporting, analytics, storage, etc. This is sometimes referred to as a Mobile Backend. GET (HTTP Method) The HTTP method for retrieving resources from a RESTful API.

Header The header is what’s sent preceding the body of an HTTP request or response. Host Header containing the domain name of the request URL.

HTTP Hypertext Transfer Protocol is how websites and APIs communicate over the internet. HTTP Method The part of an HTTP request that tells the server what the client wants to do. HTTPS Hypertext Transfer Protocol Secure is how websites and APIs communicate securely over the internet. JavaScript A dynamic programming/scripting language most commonly used in web browsers, client side scripts to interact with users and more recently to provide server side capabilities. JSON Javascript Object Notation is a data format commonly used for APIs requests parameters and response body 22 API Standard

Latency The total time it takes for the API request to go from the request to the response. Mobile Backend Provides a model for web and mobile development to host APIs and provides user management, reporting, push notifications and storage. Oauth Open standard authorization framework. Grants access on behalf of an end-user without directly sharing credentials. Open API An API that meets the principles of openness by being discoverable, documented and accessible. Orchestration The act of combining multiple actions or services to perform on a coarser grain function. Parameter A parameter is an argument sent to the API, which helps define the request and expected response. POST (HTTP Method) The HTTP method for creating resources with a RESTful API.

Protocol A defined way of transferring data between peers.

Mediation A pattern that transforms one protocol or message format to another. Example, REST to SOAP, SOAP to REST, JSON to XML, XML to JSON. Proxy An intermediary for requests from clients and servers providing resources. PUT (HTTP Method) The HTTP method for updating resources with a RESTful API.

Representation Data that describes the state of a resource. Often the body of an HTTP request/response. Resource A resource is some object or entity that has a URI where it can be manipulated through HTTP requests. REST Representational state transfer (REST) is an architectural pattern for interacting with resources via HTTP methods. SDK Software Development Kit is a set of development tools that allows developers to program against a certain software package, software framework and hardware platform. Server The server is software or hardware that provides a service by responding to requests across a network. SLA Service Level Agreements are a form of contract between a service provider and consumer defining expected performance metrics. SOAP Simple Object Access Protocol (SOAP) is a specification for exchanging structured information over the internet. SSL Secure Sockets Layer. A cryptographic protocol that secures traffic on the internet. Status Code HTTP status codes are what the server sends in the response back to the client with regards to the status of the request. URI Unique Resource Identifier is a string of characters used to identify a name of a resource. Versioning Assigning a unique identifier to keep track of the state of the API. If changes are made to the API, which breaks compatibility, the version should change. Web Service Web Service is used to describe an API that is accessible over the internet through HTTP. XML Extensible markup language is a structured format that is used to describe documents and data.

23 API Standard

APPENDIX B – ABBREVIATIONS (See Appendix A – Definitions for any terms not listed here).

AIIA Australian Information Industry Association AMQP Advanced Message Queuing Protocol ASCII American Standard Code for Information Interchange ASD Australian Security Directorate ASIO Australian Secret Intelligence Organisation BCM Business Continuity Management BLE Bluetooth Low Energy BYOD Bring Your Own Device CMIS Content Management Interoperability Services CMS Content Management System CSA Canadian Standards Association FTP File Transfer Protocol GovDC Government Data Centre GUI Graphical User Interface ICT Information & Communication Technology IoT Internet of Things ISO/TC International Organization for Standardization / Technical Committee IT Information Technology LDAP Lightweight Directory Access Protocol MQTT Message Queuing Telemetry Transport NFC Near Field Communications OCR Optical Character Recognition OS Operating System PCI-DSS Payment Card Industry – Data Security Standard PTS Procurement & Technical Standards QR Quick Response RAML RESTful API Modelling Language RTCE Real Time Collaborative Editing SAML Security Assertion Markup Layer SFTP Secure File Transfer Protocol SOA Service Oriented Architecture SOAP Simple Object Access Protocol SSO Single Sign On WADL Web Application Design Language XMPP Extensible Messaging Presence Protocol

24 API Standard

APPENDIX C – RELATED DOCUMENTS This standard should be read in conjunction with the following related documents:

 NSW Government ICT Investment Policy and Guidelines which establishes a collaborative approach to ICT investment across government. This policy supports agencies to leverage existing data, information and technology investments, and identify enablers with whole of government benefit.  NSW Government Open Data Policy which makes explicit the NSW Government’s commitment to open data and open government. This policy aims to simplify the public release of appropriate government data for use by industry and the community.  NSW Government Guidelines for Publishing Spatial Web Services which address specific requirements for enabling geospatial interoperability.

Agencies should also have regard to the following statutes, NSW Government policies and standards:

 AS/NZS ISO 31000 Risk management – Principles and guidelines  Electronic Transactions Act 2000  Government Information (Public Access) Act 2009  Health Records and Information Privacy Act 2002  ISO 27031-2011 Information technology – Security techniques – Guidelines for information and communication technology readiness for business continuity  ISO 27001 Information technology – Security techniques – Information security management systems – Requirements  NSW Government Digital Information Security Policy  NSW Government Cloud Policy  NSW Government ICT Strategy  NSW Government Digital + 2015 Final Update  NSW Government Information Classification, Labelling and Handling Guidelines  NSW Procurement: Small and Medium Enterprises Policy Framework  Privacy and Personal Information Protection Act 1998  Public Finance and Audit Act 1983  Public Interest Disclosures Act 1994  State Records Act 1998  TPP 09-05 - Internal Audit and Risk Management Policy for the NSW Public Sector

25 API Standard

APPENDIX D – STANDARDS

Developing technical standards Development of a standard begins with identifying the need for a new standard, which is followed by the development of the standard in consultation with the industry and experts groups, including the Australian Information Industry Association (AIIA). The following diagram outlines the process.

The ICT Procurement and Technical Standards Working Group (PTS Working Group) is chaired by the Department of Finance, Services & Innovation and includes senior representation from across NSW Government.

Agencies engage with the PTS Working Group concerning services for inclusion in the ICT Services Catalogue. This drives the development of technical standards, where none exist. The PTS Working Group has the leading role in reviewing and endorsing the technical standards developed in response to agencies’ requirements.

The PTS Working Group is supported by two sub-groups responsible for the areas of Telecommunications and Services and Solutions. The sub-groups are responsible for initial development and review of standards relating to their areas of responsibility.

Management and implementation There is scope to modify standards through the NSW Government ICT governance arrangements as necessary. Standards are designed to add value, augment and be complementary to, other guidance, and they are continually improved and updated. This standard does not affect or override the responsibilities of an agency or any employee regarding the management and disposal of information, data, and assets. Standards in ICT procurement must also address business requirements for service delivery. NSW Procurement facilitates the implementation of the standards by applying them to the goods and services made available through the ICT Services Catalogue.

26