tombcghtech/api_guidelines huggingface dataset:
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
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
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
The Information Technology Infrastructure Library is a set of detailed practices for IT activities such as IT service management and IT asset management that focus on aligning IT services with the needs of business. Source: ITIL — Wikipedia, https://en.wikipedia.org/wiki/ITIL