Skip to content

Commit 5dcbc8f

Browse files
elliot-huffmanelliot-huffman
committed
Fix Charts + API Routes
The API routes had the wrong capitalization and were missing prefixes. In the case of the health check route, it was completely wrong. Remove an un-needed chart on the reference index page since the architecture pages have the expected content. Correct some wording.
1 parent ae9360e commit 5dcbc8f

File tree

3 files changed

+42
-82
lines changed

3 files changed

+42
-82
lines changed

‎docs/Data-Gateway/Reference/index.md‎

Lines changed: 11 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,11 @@ This page is a hub for the **Data Gateway** reference material: how to authentic
2323
## Authentication
2424

2525
Data Gateway uses **Entra ID** (Microsoft identity platform) for authentication.
26-
All requests must include a valid **OAuth 2.0 access token** in the `Authorization` header.
26+
All requests must include a valid **JSON Web Token (Bearer/Access Token)** in the `Authorization` header.
2727

2828
### Steps
2929

30-
1. Sign in with your organization's Entra ID account to obtain an access token for the Data Gateway application.
30+
1. Sign in with your organization's Entra ID principal to obtain an access token for the Data Gateway application.
3131
2. Include the token in each API request:
3232

3333
```bash
@@ -39,21 +39,21 @@ curl -sS https://api.shilab.com/datagateway/status \
3939
### Notes
4040

4141
- Tokens are validated by the API; users do **not** access SQL or Storage directly.
42-
- Tokens expire; refresh them using your chosen OAuth flow (authorization code, client credentials, etc.).
42+
- Tokens expire; refresh them using your chosen auth flow (authorization code, client credentials, etc.).
4343
- LicenseGPT prompts and responses are **not persisted** - the API returns results to the UI for the current session.
4444

45-
## Endpoint families (overview)
45+
## Endpoint Families
4646

4747
| Family | Purpose | Typical methods | Common paths* |
4848
|---|---|---|---|
49-
| **Health & metadata** | Service liveness and basic info | `GET` | `/status` |
50-
| **Tenants** | Read and maintain tenant metadata (display name, parent association) | `GET`, `PATCH` | `/tenant`, `/tenant/{tenantId}` |
51-
| **LicenseGPT** | AI-assisted licensing & compliance analysis | `POST` | `/chat/licenseGpt` |
49+
| **Health & metadata** | Service liveness and basic info | `GET` | `/Api/Core/Health` |
50+
| **Tenants** | Read and maintain tenant metadata (display name, parent association) | `GET`, `PATCH` | `/Api/Tenant`, `/Api/Tenant/{tenantId}` |
51+
| **LicenseGPT** | AI-assisted licensing & compliance analysis | `POST` | `/Api/Chat/LicenseGpt` |
5252
| **Updates (channels & rings)** | Resolve version and retrieve update package | `GET` (and streaming) | See Swagger (“Updates”) |
5353

5454
\* For the complete, authoritative list (parameters, schemas, and responses), use the live reference at **[specs.shilab.com](https://specs.shilab.com)**.
5555

56-
## Request & response basics
56+
## Request & Response Basics
5757

5858
- **Protocol:** HTTPS only
5959
- **Content type:** `application/json; charset=utf-8` (unless explicitly streaming binaries)
@@ -62,37 +62,10 @@ curl -sS https://api.shilab.com/datagateway/status \
6262

6363
## Error handling
6464

65-
The API uses standard HTTP status codes with JSON error payloads.
65+
The API uses standard HTTP status codes with JSON error payloads. Please see [MDN - Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) for more details on specific codes and how they should be interpreted.
6666

67-
| Code | Meaning |
68-
|---|---|
69-
| `200–299` | Success |
70-
| `400` | Validation or malformed request |
71-
| `401` | Missing/invalid token |
72-
| `403` | Authenticated but not authorized |
73-
| `404` | Resource not found |
74-
| `409` | Conflict (e.g., invalid state for requested change) |
75-
| `5xx` | Service error |
76-
77-
> The response body typically includes an explanatory message; consult Swagger for exact schemas.
78-
79-
## Visual map
80-
81-
```mermaid
82-
flowchart LR
83-
C[Client app or script] --> API[Data Gateway API]
84-
85-
API --> H[Health]
86-
API --> T[Tenants]
87-
API --> G[LicenseGPT]
88-
API --> U[Updates]
89-
90-
API -. data access via API only .- DS[Data stores]
91-
92-
DS --> SQL[Azure SQL Database]
93-
DS --> BLOB[Azure Blob Storage]
94-
DS --> ATAB[Azure Table Storage]
95-
```
67+
!!! note
68+
The response body typically includes an explanatory message; consult Swagger for exact schemas.
9669

9770
---
9871

‎docs/Data-Gateway/Usage-Guide/index.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ With Data Gateway you can:
2222
### LicenseGPT
2323

2424
- Conversational interface for licensing and compliance analysis
25-
- Uses the API endpoint `POST /chat/licenseGpt`
25+
- Uses the API endpoint `POST /Api/Chat/LicenseGpt`
2626
- Combines data from **Azure SQL Database** (processed relational data) and **Azure Blob Storage** (bulk + update packages)
2727
- Can surface **agentic actions**, such as:
2828
- Retrieve License Report
@@ -35,12 +35,12 @@ flowchart TB
3535
UI["LicenseGPT (UI)"]
3636
3737
subgraph DG["Data Gateway API"]
38-
ChatEP["/chat/licenseGpt"]
38+
ChatEP{{"/Api/Chat/LicenseGpt"}}
3939
end
4040
4141
subgraph Data["Data Sources"]
42-
SQL[["Azure SQL Database - Processed Data"]]
43-
Blob[["Azure Blob Storage - Bulk & Updates"]]
42+
SQL[("Azure SQL Database - Processed Data")]
43+
Blob[/"Azure Blob Storage - Bulk & Updates"\]
4444
end
4545
4646
User --> UI
@@ -60,15 +60,15 @@ flowchart TB
6060

6161
- Displays tenant metadata: **Tenant ID**, **Display Name**, **Parent association**
6262
- Supports three operations:
63-
- **Rename** → PATCH `/tenant/{id}` to update the display name
64-
- **Associate** → PATCH `/tenant/{id}` to set a parent tenant ID
65-
- **Disassociate** → PATCH `/tenant/{id}` to clear the parent reference
63+
- **Rename** → PATCH `/Api/Tenant/{id}` to update the display name
64+
- **Associate** → PATCH `/Api/Tenant/{id}` to set a parent tenant ID
65+
- **Disassociate** → PATCH `/Api/Tenant/{id}` to clear the parent reference
6666
- All operations persist to the backend database and are reflected in downstream reporting
6767

6868
```mermaid
6969
flowchart LR
70-
UI["Tenant Manager (UI)"] --> API["Data Gateway API (/tenant)"]
71-
API --> SQL[["Azure SQL Database - Tenant Records"]]
70+
UI["Tenant Manager (UI)"] --> API{{"Data Gateway API (/Api/Tenant)"}}
71+
API --> SQL[("Azure SQL Database - Tenant Records")]
7272
```
7373

7474
!!! info "Use case"
@@ -85,13 +85,13 @@ For automation and integration, use the **public OpenAPI specification**:
8585

8686
Key endpoints:
8787

88-
- `POST /chat/licenseGpt` - AI-assisted licensing queries
89-
- `GET /tenant` - retrieve tenant metadata
90-
- `PATCH /tenant/{tenantId}` - rename, associate, or disassociate tenants
88+
- `POST /Api/Chat/LicenseGpt` - AI-assisted licensing queries
89+
- `GET /Api/Tenant` - retrieve tenant metadata
90+
- `PATCH /Api/Tenant/{tenantId}` - rename, associate, or disassociate tenants
9191
- Endpoints for bulk report retrieval and update package resolution (see Swagger)
92-
- `GET /status` - health check
92+
- `GET /Api/Core/Health` - health check
9393

94-
All requests require authentication with **Entra ID tokens** passed as HTTPS bearer tokens.
94+
All requests require authentication with **Entra ID tokens** passed as HTTPS bearer tokens, except for the health check.
9595

9696
---
9797

‎docs/Data-Gateway/index.md‎

Lines changed: 17 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -44,55 +44,42 @@ Data Gateway helps you:
4444

4545
```mermaid
4646
flowchart LR
47-
4847
%% ==========================================================
4948
%% Data Gateway - High-level Architecture (Accessible + Modern)
5049
%% Shapes communicate category:
5150
%% External: ([ ... ]) Components: [ ... ]
5251
%% Data store: [[ ... ]] AI assistant: (( ... ))
5352
%% ==========================================================
5453
55-
%% ---- Accessible, high-contrast style classes ----
56-
classDef boundary fill:#F9FAFB,stroke:#5B6472,stroke-width:1.25px,rx:10,ry:10,color:#1F2937;
57-
classDef external fill:#FFF4E6,stroke:#B45309,stroke-width:1.25px,rx:12,ry:12,color:#1F2937;
58-
classDef component fill:#E8F1FF,stroke:#1D4ED8,stroke-width:1.25px,rx:8,ry:8,color:#0B1736;
59-
classDef datastore fill:#ECFDF5,stroke:#047857,stroke-width:1.25px,rx:8,ry:8,color:#0B1736;
60-
classDef ai fill:#F5F3FF,stroke:#6D28D9,stroke-width:1.25px,rx:8,ry:8,color:#0B1736;
61-
6254
%% ---- External actors ----
63-
U([Users]):::external
64-
IDP([Entra ID Sign in and Tokens]):::external
55+
U([Users])
56+
IDP{"Entra ID (IDP)"}
6557
6658
%% ---- SHI Cloud trust boundary ----
6759
subgraph CLOUD [SHI Cloud]
6860
direction LR
6961
7062
%% Core app components (rectangles)
71-
UI[Data Gateway UI]:::component
72-
API[Data Gateway API]:::component
63+
UI[Data Gateway UI]
64+
API{{Data Gateway API}}
7365
7466
%% Data layer (double borders)
75-
BLK[[Azure Blob Storage Bulk Data]]:::datastore
76-
UPD[[Azure Blob Storage Update Packages]]:::datastore
77-
SQL[[Azure SQL Database Processed Data]]:::datastore
67+
BLK[/Azure Blob Storage Bulk Data\]
68+
UPD[/Azure Blob Storage Update Packages\]
69+
SQL[(Azure SQL Database Processed Data)]
7870
7971
%% AI assistant (circle)
80-
LLM((LicenseGPT Azure OpenAI)):::ai
72+
LLM([LicenseGPT Azure OpenAI])
8173
end
8274
83-
class CLOUD boundary
84-
8575
%% ---- Flows ----
86-
U -->|HTTPS| UI
87-
UI -->|OAuth2 Sign in| IDP
88-
IDP -->|Tokens| UI
89-
UI -->|HTTPS JWT| API
90-
91-
API -->|Read Write| BLK
92-
API -->|Read Write| UPD
93-
API -->|ORM| SQL
94-
API -->|LLM Calls| LLM
95-
96-
linkStyle 1 stroke-dasharray:6 4,stroke:#5B6472,stroke-width:1.25px
97-
linkStyle 2 stroke-dasharray:6 4,stroke:#5B6472,stroke-width:1.25px
76+
U -->| HTTPS | UI
77+
UI -->| Public/Secret Client Auth Flow | IDP
78+
IDP -->| Auth Code/Tokens | UI
79+
UI -->| HTTPS + JWT | API
80+
81+
API -->| Read Write | BLK
82+
API -->| Read Write | UPD
83+
API -->| ORM | SQL
84+
API -->| LLM Calls | LLM
9885
```

0 commit comments

Comments
 (0)