From c62e38f824f2916a033f5d63b51a8e40a1cd3327 Mon Sep 17 00:00:00 2001 From: Martin McCaffery Date: Mon, 8 Dec 2025 17:23:44 +0100 Subject: [PATCH] feat(sdk): complete first draft of EdgeConnect SDK docs --- .../edgeconnect/edgeconnect-sdk.md | 102 ++++++------------ 1 file changed, 30 insertions(+), 72 deletions(-) diff --git a/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md index 152d044..1b215b1 100644 --- a/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md +++ b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md @@ -1,9 +1,9 @@ --- -title: "EdgeConnect SDK" -linkTitle: "EdgeConnect SDK" +title: EdgeConnect SDK +linkTitle: EdgeConnect SDK weight: 10 description: > - Software Development Kit for establishing EdgeConnect connections + Software Development Kit for interacting with EdgeConnect --- {{% alert title="Draft" color="warning" %}} @@ -12,7 +12,7 @@ description: > * **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) * **Assignee**: Waldemar * **Status**: Draft -* **Last Updated**: YYYY-MM-DD +* **Last Updated**: 2025-12-08 * **TODO**: * [ ] Add detailed component description * [ ] Include usage examples and code samples @@ -22,38 +22,44 @@ description: > ## Overview -[Detailed description of the component - what it is, what it does, and why it exists] +The EdgeConnect SDK is a Go library which provides a simple method for interacting with Edge Connect within programs. It is designed to be used by other tools, such as the [EdgeConnect Client](/docs/components/deployments/edgeconnect/edgeconnect-client/) or [Terraform provider](/docs/components/orchestration/infrastructure/provider/), ## Key Features -* [Feature 1] -* [Feature 2] -* [Feature 3] +* Allows querying endpoints without the need to manage API calls and responses directly +* Wraps the existing [Edge Connect API](https://swagger.edge.platform.mg3.mdb.osc.live/) +* Supports multiple unnumbered versions of the API ## Purpose in EDP +No system can be considered useful unless it is actually, in practice, used. While the Edge Connect [console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) and [API](https://swagger.edge.platform.mg3.mdb.osc.live/) are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API. These include a [command-line tool](/docs/components/deployments/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/components/orchestration/infrastructure/provider/). + +While each such tool could simply independently wrap existing endpoints, this is generally too low-level for sustainable development. It would involve extensive boilerplate code in each such package, plus small changes to API endpoints or error handling may require constant rework. + +To avoid this, the Edge Connect SDK aims to provide a common library for interacting with EdgeConnect, allowing the abstraction of HTTP requests and authentication procedures while nonetheless allowing access directly to the endpoints available. + [Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] ## Repository -**Code**: [Link to source code repository] +**Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client -**Documentation**: [Link to component-specific documentation] +**Documentation**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk ## Getting Started ### Prerequisites -* [Prerequisite 1] -* [Prerequisite 2] +* Golang +* Edge Connect credentials ### Quick Start [Step-by-step guide to get started with this component] -1. [Step 1] -2. [Step 2] -3. [Step 3] +1. Simply [import](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#installation) the SDK to your project +2. [Initialise and configure](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#configuration-options) a client with your credentials +3. [Build](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#examples) your code around the existing endpoints ### Verification @@ -61,68 +67,20 @@ description: > ## Usage Examples -### [Use Case 1] - -[Example with code/commands showing common use case] - -```bash -# Example commands -``` - -### [Use Case 2] - -[Another common scenario] - -## Integration Points - -* **[Component A]**: [How it integrates] -* **[Component B]**: [How it integrates] -* **[Component C]**: [How it integrates] - -## Architecture - -[Optional: Add architectural diagrams and descriptions] - -### Component Architecture (C4) - -[Add C4 Container or Component diagrams showing the internal structure] - -### Sequence Diagrams - -[Add sequence diagrams showing key interaction flows with other components] - -### Deployment Architecture - -[Add infrastructure and deployment diagrams showing how the component is deployed] - -## Configuration - -[Key configuration options and how to set them] +See [README](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk#examples) for simple code examples, or repositories for [EdgeConnect Client](/docs/components/deployments/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/components/orchestration/infrastructure/provider/) for full projects relying on it. ## Troubleshooting -### [Common Issue 1] +### Varying code versions -**Problem**: [Description] +**Problem**: While the Edge Connect API does not (at time of writing) have different semantic versions, it does have different iterations which function differently. The SDK provides two different libraries, labelled [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect/v2). -**Solution**: [How to fix] - -### [Common Issue 2] - -**Problem**: [Description] - -**Solution**: [How to fix] +**Solution**: If you receive errors when using the SDK, consider changing the version you import: +```go +import v1 "edp.buildth.ing/DevFW-CICD/edge-connect-client/sdk/edgeconnect" +import v2 "edp.buildth.ing/DevFW-CICD/edge-connect-client/v2/sdk/edgeconnect/v2" +``` ## Status -**Maturity**: [Production / Beta / Experimental] - -## Additional Resources - -* [Link to external documentation] -* [Link to community resources] -* [Link to related components] - -## Documentation Notes - -[Instructions for team members filling in this documentation - remove this section once complete] +**Maturity**: Beta