Replies: 3 comments 4 replies
-
|
Why don't you use a field like |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
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) vsMetadata.Name(Spec) vshandle(Database)REST API Layer
The REST API uses
idas a path parameter to retrieve unique API artifacts:api-platform/gateway/gateway-controller/api/openapi.yaml
Line 206 in ae1c11c
API Specification
This corresponds to
Metadata.Namein the api.yaml specification:api-platform/gateway/gateway-controller/api/openapi.yaml
Lines 1310 to 1318 in ae1c11c
Data Layer
However, in the database schema, this field is persisted as
handle:api-platform/gateway/gateway-controller/pkg/storage/gateway-controller-db.sql
Line 15 in 469d74b
Impact:
The inconsistency between
id→Metadata.Name→handleacross layers creates potential confusion and increases cognitive load for developers working across the stack.Issue 2:
name(REST API) vsSpec.DisplayName(Spec) - Potential Conflict withMetadata.NameREST API Layer
The REST API uses
namefor query parameters and response fields:api-platform/gateway/gateway-controller/api/openapi.yaml
Lines 151 to 158 in ae1c11c
api-platform/gateway/gateway-controller/api/openapi.yaml
Lines 1766 to 1768 in ae1c11c
API Specification
This maps to
Spec.DisplayNamein the api.yaml specification:api-platform/gateway/gateway-controller/api/openapi.yaml
Lines 1330 to 1336 in ae1c11c
Impact:
Using
namein the REST API to representSpec.DisplayNamemay cause confusion withMetadata.Name(which is exposed asidin the REST API). This ambiguity becomes especially problematic when:Beta Was this translation helpful? Give feedback.
All reactions