TABLE OF CONTENTS

• Introduction
  • Key Features
  • Customization Scenarios
• Overview of Custom API
• Scope of Custom API
• Project Structure
  • Custom.API.Core
  • Engine.Custom.API
• Implementation Overview
  • Example: Get Order List API
• How to Customize Znode API Requests
  • Customizing Post Requests
  • Customizing Get Requests
  • GET Request Example
• Identifying and Utilizing Client Names in Znode 10
  • Installing NuGet Packages
• Important Notes
  • Limitations
• API Gateways
  • Priority Setting
• Questions and Answers
  • Q: How do I deploy the newly created Custom API?
  • Q: How can I display custom table data in a specific section?
• Debugging in Custom API
  • Setting Up Cloudflare Tunnel for Local Debugging
  • Step 1: Install and Configure Cloudflared
  • Step 2: Start the Tunnel
  • Step 3: Debugging

Introduction

This article provides comprehensive instructions on customizing API components in Znode 10 to accommodate client-specific requirements. It outlines how to extend, integrate, and enhance platform behavior effectively, without compromising Znode’s core functionalities.

Note: Znode 10 enforces restrictions on modifications across all components except the Webstore Application and Custom APIs. All customizations must align with platform-prescribed patterns to ensure long-term stability.

The Custom API is a flexible interface designed to introduce client-specific functionality within the Znode 10 framework. This structured approach supports customized enhancements without compromising Znode’s core stability.

Key Features

• Supports dynamic adjustments to API responses.
• Enables custom data posting and logic processing.
• Functions as an isolated component with no direct access to the Znode database or Entity Framework.
  
  

Customization Scenarios

Use cases for Custom API include:

• Adding new endpoints or logic.
• Modifying response structures.
• Integrating with third-party systems.
  
  

Overview of Custom API

Custom APIs serve as standalone modules that provide:

• Tailored logic and feature extensions.
• Third-party integration points.
• Safeguards against core platform disruption.
  
  

Authentication is managed through the Znode API ecosystem and handled via the Backend-for-Frontend (BFF) client.

Scope of Custom API

• No direct access to the Znode database or Entity Framework.
• Custom APIs operate within the existing Znode authentication model.
• Custom API calls are routed via API gateways.
  
  

Project Structure

The Custom API project is divided into two primary libraries:

Custom.API.Core

• Controllers: Handle user input and define API routes.
• Services: Contain business logic and service interfaces.
• CustomDependencyRegistration: Manages dependency injection for services and clients.
• References: Use Znode10.Engine.Api.Client for communication with Znode APIs.
  
  

Engine.Custom.API

• Program.cs: Configures middleware, dependency injection, and startup logic.
• SwaggerConfig.cs: Manages Swagger documentation.
• Ocelot Folder: Contains routing configurations. Routes redirect requests from the API gateway to the Custom API.
• AppSettings: Configure ZnodeApiDomainName and other critical keys required for Znode domain-based authentication.
  Note: Route keys in Ocelot must use "customapi" to ensure correct routing.
  
  

Implementation Overview

Use the CustomAPICore Template to:

• Build custom services and controllers.
• Interact with Znode Web APIs using the ZnodeClient.
• Avoid direct database access to preserve platform integrity.
  
  

Example: Get Order List API

• The template includes a sample API that calls the Znode Order endpoint.
• Modify or extend the included services to customize the behavior.
  
  

How to Customize Znode API Requests

Customizing Post Requests

Apply changes before calling the Multifront API to modify outgoing data.

Customizing Get Requests

Apply changes after the Multifront API returns data, allowing response transformation.

GET Request Example

Use service methods with provided Znode clients (e.g., _orderclient). Modifications can occur before or after the call, based on requirements.

Identifying and Utilizing Client Names in Znode 10

Each API exposes client classes via Swagger and NuGet packages:

• Znode Multifront API
  • URL: /swagger/index.html
  • Package: Znode.Multifront.API.Client
• Payment API
  • Package: Znode10.Payment.API.Client
• Custom Table API
  • Package: Znode10.Engine.CustomTable.Client

Installing NuGet Packages

Install required packages from the Znode NuGet source to access client classes such as OrderClient.

Important Notes

• Custom APIs must be hosted within the same Virtual Network (VNET) as the Multifront API for optimal performance.
• Use the Znode CLI tool to deploy the Custom API.
• For SDK-specific configurations, refer to the SDK Guideline Document.
  
  

Limitations

• Custom APIs rely entirely on Multifront APIs; direct database access is not allowed.
• Requests to modify Multifront APIs must go through support tickets.

API Gateways

Adding Custom APIs to the Ocelot Folder

• Location: Ocelot directory
• File: CustomOcelot.json
• Purpose: Redirect requests to the Custom API instead of the Znode Multifront API.

Note: Use the "key" parameter with the value "customapi" consistently across all routes.

Priority Setting

• Set a higher priority for Custom API routes compared to Znode routes to ensure they take precedence.
• A sample configuration is provided within the Custom API project.
  
  

Questions and Answers

Q: How do I deploy the newly created Custom API?

A: Use the Znode CLI command:

Znode deploy CustomAPISDK <Environment> <optional: SDK path>

After deployment, access your endpoint at:

https://<CustomAPISDKHostedURL>/<Controller>/<Action>

You may use this endpoint in the Admin Console or through the gateway configuration.

Q: How can I display custom table data in a specific section?

• Create a Custom API that fetches data from a custom database using Znode conventions.
• Deploy the API using the Znode CLI.
• Link the deployed API URL in the gateway or use it in the Admin Console.

Debugging in Custom API

Setting Up Cloudflare Tunnel for Local Debugging

Use Cloudflare Tunnels to route API workflows to your local environment for debugging.

Step 1: Install and Configure Cloudflared

• Download and install Cloudflared.
• Follow the Cloudflare Tunnel setup guide for your operating system.
  
  

Step 2: Start the Tunnel

• Launch your local Custom API (e.g., https://localhost:7222)
• In a command prompt, run:

cloudflared tunnel --url https://localhost:7222

• Copy the generated tunnel URL.
• Update the microservice (Admin or Gateway) with the new tunnel URL.
  
  

Step 3: Debugging

• Set breakpoints in your Custom API.
• Perform an action that hits the custom endpoint (e.g., update account).
• Confirm that the debugger triggers correctly.
  
  

⚠️ Important:
 After debugging, remove the tunnel URL to prevent production traffic from being routed to the local machine.