Commit 7f009c24 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs: integrate API documentation into overview views 

Reuse API descriptions, usage guidance, use cases and benefits from
feat/api-documentation, using the existing overview layouts and a shared
Markdown renderer. Keep API metadata and operations sourced from OpenAPI.

Map the application documentation to Edge Application Management and
adjust QoD guidance for the deployed API version.

Source-commit: ae383e27
Co-authored-by: default avatarMarinela Mertiri <marmert@intracom-telecom.com>
parent 0335d787

portal-gui/package-lock.json

+1071 −44

File changed.

Preview size limit exceeded, changes collapsed.

portal-gui/package.json

+1 −0
Changes for portal-gui/package.json: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -26,6 +26,7 @@ 
    "radix-ui": "^1.4.3",

    "react": "^19.2.4",

    "react-dom": "^19.2.4",

    "react-markdown": "^10.1.0",

    "react-router-dom": "^6.30.3",

    "shadcn": "^4.2.0",

    "sonner": "^2.0.7",

portal-gui/src/components/common/markdown.tsx

0 → 100644
+9 −0
Changes for portal-gui/src/components/common/markdown.tsx: 9 added lines, 0 removed lines.
Original line number Diff line number Diff line 
import ReactMarkdown from 'react-markdown';



export function Markdown({ children }: { children: string }) {

  return (

    <div className="space-y-4 leading-7 [overflow-wrap:anywhere] text-muted-foreground [&_a]:text-primary [&_a]:underline [&_code]:rounded [&_code]:bg-muted [&_code]:px-1 [&_code]:text-sm [&_li]:mt-1 [&_ol]:list-decimal [&_ol]:pl-6 [&_strong]:font-semibold [&_strong]:text-foreground [&_ul]:list-disc [&_ul]:pl-6">

      <ReactMarkdown>{children}</ReactMarkdown>

    </div>

  );

}

portal-gui/src/features/apis/api-details-page.tsx

+17 −7
Changes for portal-gui/src/features/apis/api-details-page.tsx: 17 added lines, 7 removed lines.
Original line number Diff line number Diff line 
import { useOutletContext } from 'react-router-dom';

import { SectionTitle } from '@/components/common/section-title';

import { PageContent } from '@/components/common/page-content';

import { Markdown } from '@/components/common/markdown';

import { Separator } from '@/components/ui/separator';

import {

  Card,
@@ -12,12 +13,16 @@ import { 
import { Badge } from '@/components/ui/badge';



import type { Api } from '@/types/api';

import { apiDocumentation } from '@/lib/data/api-documentation';



import SwaggerUI from 'swagger-ui-react';

import 'swagger-ui-react/swagger-ui.css';



export function ApiDetailsPage() {

  const api = useOutletContext<Api>();

  const documentation = apiDocumentation[api.id];

  const useCases = documentation?.useCases ?? api.useCases;

  const benefits = documentation?.benefits ?? api.benefits;

  return (

    <>

      <PageContent>
@@ -57,9 +62,11 @@ export function ApiDetailsPage() { 
                    Description

                  </h3>



                  <p className="mt-2 leading-7 text-muted-foreground">

                    {api.description}

                  </p>

                  <div className="mt-2">

                    <Markdown>

                      {documentation?.description ?? api.description}

                    </Markdown>

                  </div>

                </div>



                <div className="border-t pt-6 lg:border-t-0 lg:border-l lg:pt-0 lg:pr-8 lg:pl-8">
@@ -103,6 +110,9 @@ export function ApiDetailsPage() { 
                </CardHeader>



                <CardContent className="space-y-5">

                  {documentation?.instructions && (

                    <Markdown>{documentation.instructions}</Markdown>

                  )}

                  {api.operations && api.operations.length > 0 ? (

                    <div>

                      <ul className="grid gap-3 md:grid-cols-2">
@@ -152,7 +162,7 @@ export function ApiDetailsPage() { 
                  )}

                </CardContent>

              </Card>

              {api.useCases && api.useCases.length > 0 && (

              {useCases && useCases.length > 0 && (

                <Card>

                  <CardHeader>

                    <CardTitle className="text-xl font-semibold text-sidebar-primary">
@@ -166,7 +176,7 @@ export function ApiDetailsPage() { 


                  <CardContent>

                    <div className="grid gap-3 md:grid-cols-2">

                      {api.useCases.map((useCase) => (

                      {useCases.map((useCase) => (

                        <div

                          key={useCase.title}

                          className="rounded-md border bg-muted/30 p-4"
@@ -184,7 +194,7 @@ export function ApiDetailsPage() { 
                  </CardContent>

                </Card>

              )}

              {api.benefits && api.benefits.length > 0 && (

              {benefits && benefits.length > 0 && (

                <Card>

                  <CardHeader>

                    <CardTitle className="text-xl font-semibold text-sidebar-primary">
@@ -198,7 +208,7 @@ export function ApiDetailsPage() { 


                  <CardContent>

                    <div className="grid gap-3 md:grid-cols-2">

                      {api.benefits.map((benefit) => (

                      {benefits.map((benefit) => (

                        <div

                          key={benefit.title}

                          className="rounded-md border bg-muted/30 p-4"

portal-gui/src/lib/data/api-documentation.ts

0 → 100644
+314 −0
Changes for portal-gui/src/lib/data/api-documentation.ts: 314 added lines, 0 removed lines.
Original line number Diff line number Diff line 
import type { Api } from '@/types/api';



// Documentation by Marinela Mertiri (marmert), imported from commit

// ae383e27139f40598a08dbcd3383a37ec4bcc982 on feat/api-documentation.

type ApiDocumentation = Partial<

  Pick<Api, 'description' | 'useCases' | 'benefits'>

> & {

  instructions?: string;

};



export const apiDocumentation: Record<string, ApiDocumentation> = {

  'sim-swap': {

    instructions:

      'Use the SIM Swap API to check whether a recent SIM swap has occurred or to retrieve the date of the most recent SIM swap event.',



    useCases: [

      {

        title: 'Account takeover prevention',

        description:

          'Check for recent SIM swap activity before allowing sensitive account operations.',

      },

      {

        title: 'Fraud detection',

        description:

          'Use recent SIM swap information as an additional signal when assessing potentially fraudulent activity.',

      },

    ],



    benefits: [

      {

        title: 'Improved fraud prevention',

        description:

          'Provides an additional signal that can help identify suspicious account activity.',

      },

      {

        title: 'Additional security signal',

        description:

          'Enables applications to incorporate SIM swap information into their authentication and risk processes.',

      },

    ],

  },



  'edge-cloud': {

    description:

      'The “Edge Cloud” API is designed to help users discover the edge cloud zones for their applications.',



    useCases: [

      {

        title: 'Use shortest Network Path',

        description:

          'Network operators deploy edge computing zones in their networks to bring content and compute closer to user’s connected devices. \

          This can reduce latency, jitter and loss; and can ensure data communication stays within a given territory. \

          The Edge Cloud API returns the name of the edge cloud zones available. \

          You can use this information to connect the user device to an application server you already have running on this edge cloud zone or spin up an application server there if required (using the edge cloud provider’s APIs).',

      },

    ],



    benefits: [

      {

        title: 'Fulfill Network Performance Demands',

        description:

          'Applications that have strict network performance demands can benefit from deploying servers at the network edge, as can applications that wish to prevent their data from being routed on the public Internet.',

      },

      {

        title: 'Operational efficiency',

        description: 'For the API customer (cost savings) is also benefit.',

      },

    ],

  },



  'edge-application-management': {

    description: `Edge Application Management API allows API consumers to manage the Life Cycle of an Application and to Discover Edge Cloud Zones.



**Overview**



The reference scenario foresees a distributed Telco Edge Cloud where any Application Developer, known as an Application Provider, can host and deploy their application according to their specifications and operational criteria (e.g. within a specific geographical zone for data protection purposes, ensure a minimum QoS for the application clients, etc). Through Telco Edge Cloud services Developers around the globe can benefit from the traditional Cloud strengths but expertise and advantages of the Mobile Network Operators offering to their users an evolved experience for XR, V2X, Holographic and other new services.



**Introduction**



The Edge Application Management API provides capabilities for lifecycle management of application, instances and edge cloud zone discovery. Lifecycle Management allows Application Provider to onboard their application to the Edge Cloud Platform which do bookkeeping, resource validation and other pre-deployment operations. Application details can contain components network specification, package type (QCOW2, OVA, CONTAINER, HELM, CSAR), operating system details and repository to download the image of the desired application. Once the application is available on the Edge Cloud Platform, the Application Provider can instantiate the application. Edge Cloud Provider helps Application Provider to decide where to instantiate the applications allowing them to retrieve a list of Edge Cloud Zones that meets the provided criteria.



This discovery can be filtered by a specific geographical region (e.g when data residency is needed) and by status (active, inactive, unknown). Application Provider can ask the Edge Cloud Platform to instantiate the application to one or several Edge Cloud Zones that meet the criteria. Typically when more than one Edge Cloud Zone is required in the same geographic boundary, Application Provider can define instead the entire Edge Cloud Region.



Application Provider can retrieve the information of the instances for a given application, the information could be the Edge Cloud Zone where the instance is, status (ready, instantiating, failed, terminating, unknown) and endpoint (ip, port, fqdn). Application Provider can terminate an instance of an application (appInstanceId) or all the instances for a given appId.



**Definitions of terminologies commonly referred to throughout the API descriptions:**



- **Application Provider** - The provider of the application that accesses an Edge Cloud Provider to deploy its application on the Edge Cloud. An Application Provider may be part of a larger organisation, like an enterprise, enterprise customer of an Edge Cloud Provider, or be an independent entity.

- **Application** - Contains the information about the application to be instantiated. Descriptor, binary image, charts or any other package assosiated with the application. The Application Provider request contains mandatory criteria (e.g. required CPU, memory, storage, bandwidth) defined in an Application. The Edge Cloud Platform generates a unique ID for an Application that is ready to be instantiated.

- **Application Instance** - Is an instance (VM or Container based) running in an Edge Cloud Zone. The Edge Cloud Platform generates a unique ID for each instance.

- **Application Deployment** - A specification that defines the requirements for the Edge Cloud Provider to create and maintain application instances across multiple Edge Cloud Zones. The deployment ensures that the application is instantiated and managed consistently across the specified zones, meeting the defined requirements.

- **Edge Cloud** - Cloud-like capabilities located at the network edge including, from the Application Provider's perspective, access to elastically allocated compute, data storage and network resources, this access is provided through the Edge Cloud Platform.

- **Edge Cloud Provider** - Company name of the provider offering the Edge Services through the Edge Cloud Platform. Could be an Operator or a Cloud Provider.

- **Edge Cloud Region** - An Edge Cloud Region is equivalent to a Region on a Public Cloud. The higher construct in the hierarchy exposed to an Application Provider who wishes to deploy an Application on the Edge Cloud and broadly represents a geography. An Edge CloudRegion typically contains one or multiple Edge Cloud Zones. An Edge Cloud Region exists within an Edge Cloud.

- **Edge Cloud Zone** - An Edge Cloud Zone is the lowest level of abstraction exposed to an Application Provider who wants to deploy an Application on Edge Cloud. Edge Cloud Zones exists within a Edge Cloud Region.



`,

    instructions: `The usage of this API is based on several resources including GSMA Edge Platform, Public Cloud and SDOs, to define a first approach on the lifecycle management of application instances and edge cloud zones discovery.



Before starting to use the API, the developer needs to know about the below specified details.



**Application Management**



- **submitApp** - Submits application details to an Edge Cloud Provider. Based on the details provided, Edge Cloud Provider shall do bookkeeping, resource validation and other pre-deployment operations.

- **deleteApp** - Removes an application from an Edge Cloud Provider. If there is a running instance of the given application, the request cannot be done.

- **getApp** - Retrieves the information of a given application.



**Application Instance Management**



- **createAppInstance** - Request the Edge Cloud Provider to instantiate an instance of an application in a given Edge Cloud Zone. If this parameter is not set, the Edge Cloud Provider will instantiate the applications in all the Edge Cloud Zones.

- **getAppInstance** - Retrieves the list with information of the instances related to a given application.

- **deleteAppInstance** - Removes a given application instance from an Edge Cloud Zone.



**Application Deployment Management**



- **createAppDeployment** - Requests the Edge Cloud Provider to create and maintain application instances to multiple Edge Cloud Zones.

- **getAppDeployments** - Retrieves a list of deployments for a given application.

- **deleteAppDeployment** - Terminates a specific application deployment, removing all associated instances.



**Edge Cloud Information**



- **getEdgeCloudZones** - List of the operator's Edge Cloud Zones and their status, ordering the results by location and filtering by status (active/inactive/unknown).



**Authorization and authentication**



The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.



The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.



In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.



It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens become mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

`,

    useCases: [

      {

        title: 'Immersive Gaming and XR Experiences',

        description:

          'Application providers deploy latency-sensitive gaming, AR/VR or holographic workloads to the Edge Cloud zone closest to the end user, cutting round-trip latency so cloud-rendered or immersive content feels locally hosted.',

      },

      {

        title: 'Intelligent Driving and Vehicle-to-Everything (V2X)',

        description:

          'Autonomous or driver-assistance applications are instantiated on the Edge Cloud zone nearest the vehicle’s current location, so perception and control decisions are computed with minimal network delay.',

      },

      {

        title: 'Low-Latency remote Monitoring and Emergency Response',

        description:

          'Applications that process live video or sensor feeds (e.g. drone-based inspection, public-safety AI analytics) are deployed close to the data source so detection and alerting happen in near real time.',

      },

    ],

    benefits: [

      {

        title: 'Reduced Latency and improved User Experience',

        description:

          'Hosting an application on the Edge Cloud zone closest to the end user shortens the network path, benefiting latency-sensitive services such as gaming, XR and V2X.',

      },

      {

        title: 'Access to operator-grade Edge Cloud Infrastructure',

        description:

          'Application providers gain the traditional strengths of the cloud (on-demand compute, elasticity) combined with the reach and expertise of mobile network operators, without having to build or operate their own edge infrastructure.',

      },

      {

        title: 'Operational Efficiency and Cost Savings',

        description:

          'A single, standardized API to submit, deploy and manage applications and instances across one or more Edge Cloud zones reduces the integration effort and operational cost of working with multiple Edge Cloud providers.',

      },

      {

        title: 'Flexibility across Deployment Models',

        description:

          'Support for both single application instances and multi-zone deployments, and for both VM/container-based and Kubernetes-based workloads, lets application providers choose the placement model that fits their application.',

      },

    ],

  },



  'qos-sessions': {

    description: `QoS session resources can be created, queried, and deleted. Once an offered QoS profile class is requested, application users get a prioritized service with stable latency or throughput even in the case of congestion. The QoD API has the following characteristics:



- A specified App-Flow is prioritized to ensure stable latency or throughput for that flow.

- The prioritized App-Flow is described by providing information such as device IP address (or other device identifier) & application server IP addresses and port/port-ranges.

- The developer can optionally specify the duration for which they need the prioritized App-flow.

- Stable latency or throughput is requested by selecting from the list of QoS profiles made available by the service provider (e.g. QOS_E) to map latency and throughput requirements.

- The developer can optionally specify a notification URL in \`sink\` and notification credentials in \`sinkCredential\`.



`,

    instructions: `Before starting to use the API, the developer needs to know about the below specified details.



**Create a new session**



If the qosStatus in the API response is \`AVAILABLE\` and a notification callback is provided the client will receive in addition to the response a \`QOS_STATUS_CHANGED\` event notification with \`qosStatus\` as \`AVAILABLE\`.



If the \`qosStatus\` in the API response is \`REQUESTED\`, the client will receive either



- a \`QOS_STATUS_CHANGED\` event notification with \`qosStatus\` as \`AVAILABLE\` after the network notifies that it has created the requested session, or

- a \`QOS_STATUS_CHANGED\` event notification with \`qosStatus\` as \`UNAVAILABLE\` and \`statusInfo\` as \`NETWORK_TERMINATED\` after the network notifies that it has failed to provide the requested session.



A \`QOS_STATUS_CHANGED\` event notification with \`qosStatus\` as \`UNAVAILABLE\` will also be send if the network terminates the session before the requested duration expired



**NOTE**: in case of a \`QOS_STATUS_CHANGED\` event with \`qosStatus\` as \`UNAVAILABLE\` and \`statusInfo\` as \`NETWORK_TERMINATED\` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event. This behavior allows clients which are not receiving notification events but are polling to get the session information with the \`qosStatus UNAVAILABLE\`. Before a client can attempt to create a new QoD session for the same device and flow period they must release the session resources with an explicit \`delete\` operation if not yet automatically deleted.



**Get QoS session information**



Querying for QoS session resource information details



**Delete a QoS session**



Release resources related to QoS session.



If the notification callback is provided and the \`qosStatus\` of the session was \`AVAILABLE\` the client will receive in addition to the response a \`QOS_STATUS_CHANGED\` event with



- \`qosStatus\` as \`UNAVAILABLE\` and

- \`statusInfo\` as \`DELETE_REQUESTED\`



There will be no notification event if the \`qosStatus\` was already \`UNAVAILABLE\`.



**Extend the duration of an active session**



Extend the overall duration of an active QoS session. The overall duration, including the requested additional duration, shall not exceed the maximum duration fixed for the selected QoS profile. If the new duration would exceed that limit, it is capped to the profile's maximum.



For example, a QoS profile has a maximum duration of 50,000 seconds. A session was created with a duration of 30,000 seconds, and the developer requests another 30,000 seconds:



- Previous duration: 30,000 seconds

- Requested additional duration: 30,000 seconds

- New overall duration: 50,000 seconds (the maximum allowed)



`,

  },



  'qos-profiles': {

    description:

      'The “Quality-of-Service (QoS) Profiles” API provides a set of predefined network performance characteristics, \

    such as latency, throughput, and priority, identified by a unique name. \

    These profiles allow application developers to specify the desired network behavior for their application’s data traffic, \

    ensuring optimal performance. \

    By selecting an appropriate QoS profile, developers can request stable latency (reduced jitter) or throughput for specific data flows between client devices and application servers when used by the Quality On Demand API.',

    instructions: `Key Features are:



- **Discover QoS Profiles**: Retrieve all available QoS profiles offered by the API provider.

- **Profile Details**: Retrieve detailed characteristics of a specific QoS profile by name.



`,

    useCases: [

      {

        title: 'Industrial IoT',

        description:

          'Ensure stable communication for sensors and actuators in industrial environments.',

      },

      {

        title: 'VR/Gaming',

        description:

          'Provide low-latency connections for immersive virtual reality experiences and online gaming.',

      },

      {

        title: 'Live Video Streaming',

        description:

          'Maintain high-quality video streams with minimal buffering and interruptions.',

      },

      {

        title: 'Autonomous Driving',

        description:

          'Enable reliable communication for autonomous vehicles, ensuring safety and efficiency.',

      },

      {

        title: 'Telemedicine',

        description:

          'Support real-time data transmission for remote medical consultations and monitoring.',

      },

      {

        title: 'VoIP Services',

        description:

          'Providing stable and clear voice communication by prioritizing VoIP traffic.',

      },

      {

        title: 'Enterprise Applications',

        description:

          'Optimizing network performance for critical enterprise applications.',

      },

    ],

    benefits: [

      {

        title: 'Enhanced User Experience',

        description:

          'Improve application performance by ensuring stable latency and prioritized throughput.',

      },

      {

        title: 'Simplified Network Management',

        description:

          'Abstract the complexity of network technologies, allowing developers to focus on application logic.',

      },

      {

        title: 'Flexibility',

        description:

          'Choose from predefined QoS profiles to meet specific latency and throughput requirements.',

      },

      {

        title: 'Scalability',

        description:

          'Manage multiple QoS sessions efficiently, supporting a wide range of applications and devices.',

      },

      {

        title: 'Compliance',

        description:

          'Ensure compliance with privacy regulations through secure authentication and authorization mechanisms.',

      },

      {

        title: 'Operational efficiency',

        description: 'For the API customer (cost savings)',

      },

    ],

  },



  cluster: {

    description: 'View available clusters',

  },

};