Introduction to Open APIs

Systems provide APIs to allow other systems to interact with them and API contracts define the behavior and content of the system interaction.

Finastra APIs are Open APIs defined using the OpenAPI specification and they are publicly available on the Finastra Developer Portal.

This page contains the following:

• Open APIs
• OpenAPI
  • References
• Open APIs
• Open API Principles
  • Useful
  • Keep it Simple
  • Easy to Use
  • Consistent
  • Backward Compatible
• REST API Maturity Levels

Open APIs

From Wikipedia: “An open API (often referred to as a public API) is a publicly available application programming interface that provides developers with programmatic access to a proprietary software application or web service”

OpenAPI

The most common format to describe Open APIs is the OpenAPI Specification (OAS) standard which describe the structure and syntax of the document, or code, that is used to describe REST Open APIs.

Swagger is tooling that allows developers to design build and document Open APIs according to the OpenAPI Specification.

An extensive OSS community provides tools for OAS APIs such as code generator, editors, and documentation generator.

The Open API definition is agnostic to the server implementation in that the underlying services can be written in various technical stacks e.g. .NET, Spring, etc., without change to the Open API. Similarly, the underlying services are agnostic of clients calling their APIs.

A well written API allows external API developers to use the contents of the API definition to develop their own client without recourse to further documentation. This requires the API documentation to contain full details of data structures, validation rules and expected behaviors for the operations within the API.

References

• Open API Initiative
• OpenAPI v2.0
• OpenAPI v3.1.0
• Swagger Editor

---

Open APIs

APIs are Open APIs (public) as far as possible and an API should be designed so that:

• it exposes functionality in a manner that is understood by developers with domain knowledge rather than knowledge of the underlying system
• it hides the internal implementations of the system it exposes
• it is future proofed as far as possible so that it does not require significant future changes because once an API has been published it becomes difficult to change

The following rules apply:

Open API Principles

The following principles should apply when designing and developing Open APIs. These principles are aimed at API designers and developers so that they focus on the quality attributes of the API definition and the underlying API implementation.

The Open API principles are:

• Useful
• Keep it Simple
• Easy to Use
• Consistent
• Backward Compatible

It is assumed that an API First approach is adopted to deliver APIs as Products.

Useful

Rationale

Open APIs MUST be designed based on client requirements. They should contain as much information as necessary but as little as possible. They can support multiple related use cases.

Implications

Open API designers must ensure that the API’s target audience and use cases are well known so that they can fulfill product requirements.

Open API designers should adopt an iterative approach to design ensuring that design fails fast, feedback is obtained and the API is continually improved until the API is deemed useful and of production quality.

Keep it Simple

Rationale

Open APIs are used by external API developers. The successful adoption of APIs is determined by API developers’ experience. The more simple the more adoption.

Implications

Open API designers MUST assume that the API audience are:

• NOT product experts - do NOT use product specific vocabulary.
• NOT Business experts - do use known Business terminology.
• NOT Technical experts - do NOT use technical jargon.

Easy to Use

Rationale

Open APIs are not adopted if they pose any barriers to API developers.

Implications

Open API designers MUST ensure that the API is:

• Clear
• Concise
• Coherent
• Unambiguous
• Intuitive to use
• Consistent

Consistent

Rationale

Open APIs must be professional:

• They MUST be production-quality ready.
• They MUST have a look and feel that is consistent across all Open APIs.

Implications

Open API designers and developers MUST ensure that:

• standards are followed.
• Common definitions are reused where appropriate.
• Open APIs are created using linters that use Swagger rules to validate.
• Open APIs are validated as part of CI/CD using Swagger rules.
• Open APIs are approved for publication by the Open API team.

Backward Compatible

Rationale

Once a client has adopted a Open API the client expects that API to function correctly on all future releases unless the client is explicitly told that the API is being deprecated and obsoleted

Implications

Finastra Open API designers MUST ensure that:

• APIs are versioned
• Breaking changes to an API are not introduced

REST API Maturity Levels

The Richardson Maturity Model. is a way to score an API according to the constraints of the RESTful architectural style.

An API with a score of 0 is not deemed RESTful whereas an API with a score of 3 is a truly RESTful API.

The following table describes the Richardson Maturity Model:

The following rules apply:

---