A recent survey performed by SmartBear, a leading company in application programming interfaces (APIs) included more than 3000 responses from developers, architects, and quality assurance (QA) professionals.
The result of the survey reveals the importance of the experience for developers when consuming APIs that is, their usability, their quality, and how internal organisation API design guidelines help to harmonise the consumer's experience.
This document describes SWIFT-specific guidelines that should be followed when building an Open API.
SWIFT's Open APIs are based on the REST architecture:
- URLs define the query interface of the API that is, all of the endpoints that can be used to either access data that is exposed or to trigger actions.
- Representations of the resources are exchanged between the consumer and the provider. Those representations are sent through the HTTP body of the request/response and have a specific format that is JSON or XML defined in the Content-Type header of the associated request/response.
- HTTP Verbs that is, POST, GET/HEAD, PUT/PATCH, and DELETE define the actions that can be performed on the resources.
- All interactions are Stateless, meaning that the server does not store any context information associated with the consumer. State dependencies limit and restrict the scalability/elasticity of the APIs.
An API exposes a back-end service or system to a consumer.
APIs expose a back-end service or system
For more information about REST, check Roy Thomas Fielding's dissertation.
They do not consume APIs directly, but use a client application and/or a website.
For example, a user using a weather application to see weather forecasts will consume weather data from the API through the application.
Applications and/or websites used to access APIs.
They send requests to the APIs and receive responses back.
Client applications and/or websites serve the end-users.
The industry-standard protocol for authorisation.
OAuth 2.0 provides authorisation flows for web applications, desktop applications, mobile applications, and Internet of Things (IoT) applications.
SWIFT uses OAuth 2.0 for both Cloud-based APIs and MV-SIPN-based APIs.
OAuth 2.0 delivers access tokens that can then be used to access APIs on behalf of the user.
The "thing" used by client applications to make API requests on behalf of an end-user.
An access token represents the authorisation of a specific client application to access specific parts that is, the scope of the OAuth access token of a user's data.
The OAuth access token must always be sent through an HTTP over TLS that is, HTTPS secure connection using the HTTP Bearer Authentication mechanism.
Stateless application-level protocol for distributed, collaborative, hypertext information systems.
HTTP is at the heart of REST APIs.
The primary goal of TLS is to provide a secure channel between two communicating peers.
The only requirement from the underlying transport is a reliable, in-order data stream.
The TLS protocol provides authentication, confidentiality and integrity.
The TLS protocol can be implemented as either one-way or two-way:
- In one-way TLS, only the client validates the server to ensure that it receives data from the intended server. One-way TLS is always used between client applications and the API gateway.
- In two-way TLS, the client and the server authenticate each other to ensure that both parties involved in the communication are trusted. Two-way TLS is always used between the API gateway and the back-end systems.
Also called Token Authentication.
It is an HTTP authentication scheme that involves security tokens called bearer tokens.
The name "bearer authentication" can be understood as give access to the bearer of this token.
The bearer token is a cryptic string generated by the /token API proxy in response to a login request.
The client application must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>
APIs accessible through the public Internet that is, the API Gateway hosting these APIs is installed in the cloud.
Also called On-Premises APIs that is, the API Gateway hosting these APIs is installed inside SWIFT's OPCs.
Either APIs accessible through SWIFT's Multi-Vendor Secure IP Network (MV-SIPN), or APIs accessible through the public Internet BUT with additional security: two-way TLS and bearer tokens.
Set of tools for creating and publishing APIs:
- API Gateway
- API Publishing Tools
- Developer Portal
- API Reporting and Analytics
- API Monetisation
Server that acts as an API front-end, receiving API requests, enforcing throttling and security policies, passing requests to the back-end service, and passing the response back to the requester.
An API gateway can also provide functionalities such as:
- A transformation engine to orchestrate and modify the requests and responses on the fly.
- Collecting analytics data.
- Providing caching.
- Providing support for authentication and authorisation.
- Providing support for security, auditing, and regulatory compliance.
Collection of tools used to:
- Define APIs using the OpenAPI 3.0 Specification (OAS 3.0).
- Collaborate on the definition of new APIs.
- Generate API documentation (for publication on the Developer Portal).
- Generate Client SDK and Server Stubs code in several programming languages.
- Coordinate the overall API Lifecycle.
SwaggerHub is the API publishing tool used within SWIFT.
The one source of information about all APIs published by SWIFT.
SWIFT's Developer Portal provides:
- API catalogue.
- API overview (value proposition, latest updates, use cases).
- Developer-friendly reference documentation.
- Client SDKs and other collaterals, such as JSON Schemas and detailed specifications.
- API sandboxes to test APIs.
- The ability to subscribe to APIs and manage consumer keys/secrets that is, OAuth 2.0 Client ID and Client Secret.
- The ability to request support.
The Developer Portal is similar to SWIFT's Download Center in that it contains the released products related to APIs.
The content of the Developer Portal is accessible to anyone who has a swift.com account or who has created a Developer Portal account.
SwaggerHub functions as a Social Network for APIs. It enables users inside and outside of SWIFT to collaborate on the design of new or existing APIs.
The access to the API specifications in SwaggerHub is controlled, and users must ask permission to collaborate on the API specifications they are interested in.
Monitor API usage and load (for example, overall hits, completed transactions, number of data objects returned, amount of compute time and other internal resources consumed, volume of data transferred).
Can include real-time monitoring of APIs with alerts raised directly or by means of a higher-level network management system.
The reporting and analytics functionality can be used to optimise the API offering within an organization's overall continuous improvement process, and for defining service-level agreements (SLAs) for APIs.
Provide support for charging access to commercial APIs.
Set up pricing rules based on usage, load and, functionality.
The system implementing the API.
Developers creating mobile applications and/or websites for end-users.
They consume APIs by integrating them into their applications and/or websites.
They are the main users of the Developer Portal, where they can register their applications to gain access to the APIs they need.
What we expect from a consumer:
- Must respect the API design guidelines.
- Should ignore fields that are not recognised in a response.
- Should be as specific as possible when consuming versions.
- Should expect the API to be stateless.
- Should utilise resource links provided in response payload in preference to self-generated URLs.
- Could ask for additional data and/or functionality. There may be additional data and/or functionality that the API can offer to make it more useful to consumers. Valid reasons to ask for API changes are, for instance:
- The API does not support a (new) widely used API standard.
- The API only offers some information as part of a larger set.
- Should not expected dramatic changes in an API just because that would suit their needs. APIs may already have other consumers and changes might not be suitable for them.
Expose data and/or functionality by creating and operating APIs.
They typically use an API Management Platform to make their APIs available to others.
They use the Developer Portal to provide information and documentation about their APIs for the API consumers.