Technical considerations

The new requirements to expand Globex’s business by adding additional channels bring its own set of challenges:

  • Lack of a standardized API format makes really challenging to gain access to the data needed from Globex

  • Launching a Mobile App is difficult because it would be tightly coupled with the e-commerce retail application’s core services

  • Inter-dependencies between various teams during the dev phase can slow down the dev productivity and time to market.

  • Lack of governance and inadvertent changes to the services can lead to adverse effect on the dev teams

Globex decided to adopt a Contract First approach to address these challenges.

Contract First Approach

Contract-first development is a design approach where the API contract is defined before any actual code is written. The stakeholders, including business users and developers first agree upon the Contract using a definition language such as OpenAPI Specification (OAS) or AsyncAPI. This contract serves as a blueprint for the API, the structure, data formats and expected behavior, authentication methods, and other relevant information.

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs.

This approach provides a clear contract to all the relevant parties - that can be used to guide development, testing, and integration - even before writing the first line of code.

apim contract first approach
Figure 1. Full API lifecycle management

  1. Design API
    Red Hat API Designer, based on Apicurio, provides a web based visual API Designer tool to draft a an OpenAPI.

  2. Govern
    The OpenAPI specifications can then be stored in a service registry. Red Hat Service Registry is store for the OpenAPI artifacts, and acts as a system of truth.

  3. Mock & Test
    While we don’t explicitly work on this phase in this module - the Mock phase helps to define meaningful examples that can be exposed to the API consumers, and the Test phase helps to define the test cases based on the before actual implementation of the APIs.

  4. Implement, Build & Deploy

    1. The Backend Services and the Mobile/Partner App can be developed in parallel using OpenAPI specifications, allowing the mobile app team to proceed without waiting for the backend to be fully implemented.

      The Mobile App is built using Angular + NodeJS anduses angular-auth-oidc-client to enable user single sign-on (SSO).

    2. The teams then follow the organization’s release principles for building and deploying them - in this case - on OpenShift.

  5. Manage and Secure API
    The team then introduces Red Hat 3scale API management to expose, secure and manage the APIs to the core application backend services.

  6. Secure Access
    Globex uses Red Hat build of Keycloak to provide Single Sign-On (SSO) capabilities to users, web apps and APIs. In this case, OpenID Connect is used to authenticate a user (Globex Web and Mobile users) and also allow secured access to Globex’s APIs.

OpenID Connect (OIDC) is a simple identity layer on top of the popular OAuth framework, and adds support for authentication. When OIDC authentication option is used, the API requests are authenticated using the access tokens in the JSON Web Token (JWT) format

A Note on Code generation

AI tools are increasingly being utilized in generating OpenAPI specifications and corresponding server and client codebase. But irrespective of the tools or approach used, the Contract First approach is still relevant.

For this module, the server-side code for the Mobile Gateway has been built using the Apicurio Codegen Quarkus Extension. You can use the Quarkus extension from Quarkiverse to generate REST clients based on OpenAPI specification files.

API Management with 3scale

apim deployment

Red Hat 3scale API Management platform makes it easy to manage your APIs for internal or external users

  • API providers get a rich API admin portal, including performance dashboards.

  • Developer Portal serves as the central hub for API consumers and support exposing the APIs securely. Mobile developers and Partners can sign up to APIs via the 3scale Developer Portal, and also track their usage through analytics.

  • In this workshop, you will work with OpenID Connect to secure the APIs with Keycloak.

Implementation

In the next sections you will be guided through the implementation and deployment of the Contract First Approach module. Since this entails way more than can be achieved during a workshop, a number of components - such as the actual REST API Code - are already in place. You will focus on a number of key activities to deploy and run the solution.

Proceed to the Instructions for this module.