Standardize Identifier Naming Across REST API, API Artifacts, and Data Layer

[nimsara66]

Inconsistent Identifier Naming Used in REST API, API Artifacts, and Data Layer

Overview

There are naming inconsistencies between the REST API layer, the data persistence layer, and the API specification that may lead to confusion and maintenance challenges.

---

Issue 1: id (REST API) vs Metadata.Name (Spec) vs handle (Database)

REST API Layer
The REST API uses id as a path parameter to retrieve unique API artifacts:

• [Path Parameter Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Line 206 in ae1c11c

  /apis/{id}:

API Specification
This corresponds to Metadata.Name in the api.yaml specification:

• [Metadata.Name Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1310 to 1318 in ae1c11c

  	Metadata:
  	type: object
  	required:
  	- name
  	properties:
  	name:
  	type: string
  	description: Unique handle for the resource
  	example: weather-api-v1.0

Data Layer
However, in the database schema, this field is persisted as handle:

• [Database Schema]
  

  api-platform/gateway/gateway-controller/pkg/storage/gateway-controller-db.sql

  Line 15 in 469d74b

  handle TEXT NOT NULL UNIQUE, -- API handle (e.g., petstore-v1.0)

Impact:
The inconsistency between id → Metadata.Name → handle across layers creates potential confusion and increases cognitive load for developers working across the stack.

---

Issue 2: name (REST API) vs Spec.DisplayName (Spec) - Potential Conflict with Metadata.Name

REST API Layer
The REST API uses name for query parameters and response fields:

• [Query Parameter]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 151 to 158 in ae1c11c

  	parameters:
  	- name: name
  	in: query
  	required: false
  	description: Filter by API name
  	schema:
  	type: string
  	example: Weather API

• [Response Field]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1766 to 1768 in ae1c11c

  	name:
  	type: string
  	example: weather-api

API Specification
This maps to Spec.DisplayName in the api.yaml specification:

• [Spec.DisplayName Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1330 to 1336 in ae1c11c

  	displayName:
  	type: string
  	description: Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
  	minLength: 1
  	maxLength: 100
  	pattern: '^[a-zA-Z0-9\-_\. ]+$'
  	example: weather-api

Impact:
Using name in the REST API to represent Spec.DisplayName may cause confusion with Metadata.Name (which is exposed as id in the REST API). This ambiguity becomes especially problematic when:

• Returning API responses that include both fields
• Supporting export functionality for persisted api.yaml artifacts
• Developers need to understand which "name" field is being referenced

[BLasan]

Why don't you use a field like UUID or ID under meta data? Any specific reason for omitting such naming? In the spec, it's better to go with something like name. @nimsara66

[malinthaprasan]

We are trying to make our yaml similar to a K8s kind so that same yaml can be used across CLI and the operator. Hence we need to comply with k8s spec and use metadata.name.

[piyumaldk]

Inconsistent Identifier Naming Used in REST API, API Artifacts, and Data Layer

Overview

There are naming inconsistencies between the REST API layer, the data persistence layer, and the API specification that may lead to confusion and maintenance challenges.

Issue 1: id (REST API) vs Metadata.Name (Spec) vs handle (Database)

REST API Layer The REST API uses id as a path parameter to retrieve unique API artifacts:

• [Path Parameter Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Line 206 in ae1c11c

  /apis/{id}:

API Specification This corresponds to Metadata.Name in the api.yaml specification:

• [Metadata.Name Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1310 to 1318 in ae1c11c

  	Metadata:
  	type: object
  	required:
  	- name
  	properties:
  	name:
  	type: string
  	description: Unique handle for the resource
  	example: weather-api-v1.0

Data Layer However, in the database schema, this field is persisted as handle:

• [Database Schema]
  

  api-platform/gateway/gateway-controller/pkg/storage/gateway-controller-db.sql

  Line 15 in 469d74b

  handle TEXT NOT NULL UNIQUE, -- API handle (e.g., petstore-v1.0)

Impact: The inconsistency between id → Metadata.Name → handle across layers creates potential confusion and increases cognitive load for developers working across the stack.

Issue 2: name (REST API) vs Spec.DisplayName (Spec) - Potential Conflict with Metadata.Name

REST API Layer The REST API uses name for query parameters and response fields:

• [Query Parameter]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 151 to 158 in ae1c11c

  	parameters:
  	- name: name
  	in: query
  	required: false
  	description: Filter by API name
  	schema:
  	type: string
  	example: Weather API

• [Response Field]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1766 to 1768 in ae1c11c

  	name:
  	type: string
  	example: weather-api

API Specification This maps to Spec.DisplayName in the api.yaml specification:

• [Spec.DisplayName Definition]
  

  api-platform/gateway/gateway-controller/api/openapi.yaml

  Lines 1330 to 1336 in ae1c11c

  	displayName:
  	type: string
  	description: Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
  	minLength: 1
  	maxLength: 100
  	pattern: '^[a-zA-Z0-9\-_\. ]+$'
  	example: weather-api

Impact: Using name in the REST API to represent Spec.DisplayName may cause confusion with Metadata.Name (which is exposed as id in the REST API). This ambiguity becomes especially problematic when:

• Returning API responses that include both fields
• Supporting export functionality for persisted api.yaml artifacts
• Developers need to understand which "name" field is being referenced

This implementation was intentional and was discussed with @malinthaprasan.

The goal is to hide the internal concept of a "handle" from customers and expose a simpler, more intuitive API using id and name. Internally, the Platform API and Gateway use "handle" because they operate on separate databases with independent IDs, and the handle serves as a unique identifier for all.

Since the OpenAPI specification is exposed to users, we intentionally refer to these identifiers as "id" to avoid confusion and keep the external contract clean and user-friendly, while preserving the required internal separation and correctness.

If needed, we may need to revisit this.

@malinthaprasan Please note.

[nimsara66]

@renuka-fernando Please note.

[malinthaprasan]

Suggestion:

Issue 1: id (REST API) vs Metadata.Name (Spec) vs handle (Database):

This is fine as long as we don't conflit between these names. IMO, from each perspective (API, Spec, DB) those identifiers we have used are fine.

Issue 2: name (REST API) vs Spec.DisplayName (Spec) - Potential Conflict with Metadata.Name

This is a real issue.
IMO, we shouldn't use the term "name" anywhere other than the spec. We should use "displayName" instead in all the other places (API contracts, variables, table columns etc). Otherwise, definitely developers will get confused and eventually bugs will be introduced by mis-identification of name (in one place referred to handle) vs displayName. And in the REST API -> API/LLMProvider, MCPProxy payloads, we can't use both name and displayName at the same time which actually refers to the same thing.

[piyumaldk]

And in the REST API -> API/LLMProvider, MC

Ack. In that case, regarding Issue 1, lets keep this as it is. Regarding 2nd issue, I will change it to displayName in gateway controller and change the name flag in apipctl to display-name.

[piyumaldk]

@malinthaprasan sent the PR #498 PRAM