WIP - Convert Fabric APIs to TypeSpec #373

Devon-White · 2025-07-09T19:24:01Z

REST API Update Pull Request

Description

Convert all Fabric APIs to TypeSpec

Type of Change

New endpoint
Update to existing endpoint

Motivation and Context

We want to live in a world of only TypeSpec

Checklist:

I have read and fully understand the process for updating the REST API
Mandatory fields are present in the TypeSpec files.
TypeSpec files successfully compiled OpenAPI spec files.
- No new warnings were generated during the compilation process.
OpenAPI spec files were validated with a SWAGGER UI tool to ensure they are correct.
The DevEx team has been alerted with the new changed by including the team/developer-experience label in the PR.

netlify · 2025-07-09T19:24:07Z

✅ Deploy Preview for signalwire-docs ready!

Name	Link
🔨 Latest commit	`e78bc80`
🔍 Latest deploy log	https://app.netlify.com/projects/signalwire-docs/deploys/686ee9cfacc0f4000803864e
😎 Deploy Preview	https://deploy-preview-373--signalwire-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 23 (🔴 down 13 from production) Accessibility: 91 (no change from production) Best Practices: 92 (no change from production) SEO: 89 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2025-07-09T19:29:11Z

yarn run v1.22.22
$ /home/runner/work/docs/docs/node_modules/.bin/ts-node tools/scripts/generate-matrix.ts

OpenAPI Specification Analysis

Changes are compared to the main branch:

🟢 Improvements (higher scores or fewer issues)
🔴 Regressions (lower scores or more issues)
⚪ No changes

Spec	Docs	Completeness	SDK Gen	Security	Overall	Warnings	Errors	Report
`specs/compatibility-api/_spec_.yaml`	72/100 (=) ⚪	69/100 (=) ⚪	79/100 (=) ⚪	39/100 (=) ⚪	65/100 (=) ⚪	448 (=) ⚪	360 (=) ⚪	View
`specs/signalwire-rest/calling-api/tsp-output/@typespec/openapi3/openapi.yaml`	98/100 (=) ⚪	95/100 (=) ⚪	100/100 (+3.0) 🟢	52/100 (=) ⚪	86/100 (=) ⚪	16 (-4) 🟢	5 (=) ⚪	View
`specs/signalwire-rest/chat-api/tsp-output/@typespec/openapi3/openapi.yaml`	98/100 (=) ⚪	95/100 (=) ⚪	100/100 (+3.0) 🟢	52/100 (=) ⚪	86/100 (=) ⚪	10 (-2) 🟢	3 (=) ⚪	View
`specs/signalwire-rest/datasphere-api/tsp-output/@typespec/openapi3/openapi.yaml`	97/100 (=) ⚪	94/100 (=) ⚪	100/100 (+4.0) 🟢	52/100 (=) ⚪	86/100 (+1.0) 🟢	49 (-16) 🟢	17 (=) ⚪	View
`specs/signalwire-rest/fabric-api/tsp-output/@typespec/openapi3/openapi.yaml`	97/100 (+2.0) 🟢	94/100 (+2.0) 🟢	100/100 (+4.0) 🟢	52/100 (=) ⚪	86/100 (+2.0) 🟢	586 (+261) 🔴	218 (+125) 🔴	View
`specs/signalwire-rest/fax-api/_spec_.yaml`	38/100 (=) ⚪	35/100 (=) ⚪	86/100 (=) ⚪	39/100 (=) ⚪	50/100 (=) ⚪	18 (=) ⚪	15 (=) ⚪	View
`specs/signalwire-rest/logs-api/tsp-output/@typespec/openapi3/openapi.yaml`	98/100 (=) ⚪	95/100 (=) ⚪	100/100 (+4.0) 🟢	52/100 (=) ⚪	86/100 (+1.0) 🟢	9 (-2) 🟢	4 (=) ⚪	View
`specs/signalwire-rest/message-api/_spec_.yaml`	53/100 (=) ⚪	50/100 (=) ⚪	86/100 (=) ⚪	38/100 (=) ⚪	57/100 (=) ⚪	18 (=) ⚪	11 (=) ⚪	View
`specs/signalwire-rest/project-api/_spec_.yaml`	76/100 (=) ⚪	73/100 (=) ⚪	69/100 (=) ⚪	36/100 (=) ⚪	64/100 (=) ⚪	21 (=) ⚪	14 (=) ⚪	View
`specs/signalwire-rest/pubsub-api/_spec_.yaml`	98/100 (=) ⚪	95/100 (=) ⚪	88/100 (=) ⚪	36/100 (=) ⚪	80/100 (=) ⚪	11 (=) ⚪	6 (=) ⚪	View
`specs/signalwire-rest/space-api/_spec_.yaml`	75/100 (=) ⚪	72/100 (=) ⚪	88/100 (=) ⚪	40/100 (=) ⚪	69/100 (=) ⚪	372 (=) ⚪	271 (=) ⚪	View
`specs/signalwire-rest/video-api/_spec_.yaml`	86/100 (=) ⚪	85/100 (=) ⚪	86/100 (=) ⚪	39/100 (=) ⚪	74/100 (=) ⚪	179 (=) ⚪	131 (=) ⚪	View
`specs/signalwire-rest/voice-api/_spec_.yaml`	53/100 (=) ⚪	50/100 (=) ⚪	86/100 (=) ⚪	38/100 (=) ⚪	57/100 (=) ⚪	18 (=) ⚪	11 (=) ⚪	View

Done in 152.35s.

Devon-White · 2025-07-09T20:19:44Z

Should fix some of the errors in the OpenAPI report while im already here and working on this

cassieemb

I'm very sorry for all the comments, please feel free to ask for clarification on anything! I know I made a few as notes and I will come back to those shortly.

I think this is looking great overall! I think there are some copy paste issues, and a few endpoints with the wrong bodies.

These also don't feel clearly represented to me, but I might have missed it:

https://developer.signalwire.com/rest/signalwire-rest/endpoints/fabric/assign-resource-to-phone-route/

https://developer.signalwire.com/rest/signalwire-rest/endpoints/fabric/assign-resource-to-domain-application/

https://developer.signalwire.com/rest/signalwire-rest/endpoints/fabric/assign-resource-to-sip-endpoint

specs/signalwire-rest/types/status-codes/main.tsp

cassieemb · 2025-07-09T20:41:57Z

specs/signalwire-rest/fabric-api/_shared/fabric-address/models/core.tsp

+@summary("Application Address")
+model FabricAddressApp extends FabricAddress {
+  @doc("Type of the Fabric Address which is an application.")
+  @example(DisplayTypes.App)
+  type: DisplayTypes.App;
 }
+
+@summary("Room Address")
+model FabricAddressRoom extends FabricAddress {
+  @doc("Type of the Fabric Address which is a conference room.")
+  @example(DisplayTypes.Room)
+  type: DisplayTypes.Room;
+}
+
+@summary("Call Address")
+model FabricAddressCall extends FabricAddress {
+  @doc("Type of the Fabric Address which is a call.")
+  @example(DisplayTypes.Call)
+  type: DisplayTypes.Call;
+
+}
+
+@summary("Subscriber Address")
+model FabricAddressSubscriber extends FabricAddress {
+  @doc("Type of the Fabric Address which is a subscriber.")
+  @example(DisplayTypes.Subscriber)
+  type: DisplayTypes.Subscriber;
+}


thought: The phrasing of these is a little confusing to me, but I'm not coming up with any alternatives off the bat. Leaving a note here so I come back to it

After further evaluation, I think the confusing part to me is "which is a(n) X". The display types are only for presenting details in the UI and filtering results.

I'm not sure what we could say about these two. It might be best to talk to product or Bryan to understand the best phrasing for these.

@summary("Application Address") @doc("Type of the Fabric Address which is an application.")

@summary("Call Address") @doc("Type of the Fabric Address which is a call.")

I think we could rephrase this as "the display type of a fabric address pointing to a conference room".

@summary("Room Address") @doc("Type of the Fabric Address which is a conference room.")

I think we could rephrase this as "the display type of a fabric address pointing to a subscriber".

@summary("Subscriber Address") @doc("Type of the Fabric Address which is a subscriber.")

What are your thoughts?

specs/signalwire-rest/fabric-api/ai-agent/addresses/main.tsp

specs/signalwire-rest/fabric-api/call-flows/addresses/main.tsp

cassieemb · 2025-07-09T21:26:26Z

specs/signalwire-rest/fabric-api/subscribers/subscriber-tokens/models/core.tsp

    subscriber_id: uuid;

    @doc("The token that is associated with the subscriber.")
+    @format("uuid")


suggestion (non-blocking): I think "jwt" for the format

cassieemb · 2025-07-09T21:26:29Z

specs/signalwire-rest/fabric-api/subscribers/subscriber-tokens/models/core.tsp

    @example("eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiU0FUIn0..HahMYxqt4uI14qSH.daMTBR53lfEfEFiVAhr0pPSRqZhEod_YzavoG9-4ieiRQvl8GtP3FFNx0VLfkJqNcjUNbAaiKrEMnfOtCnQjiq1Kn0Iq90MYdM00QJ7cTaQ88vfbqdE92p-d4oDeg6z_vAsgrFgEobmrlDQndKxCWOD921iYxyLP0vqNaokN3kIM06iAWu_UpnTYEeR1l068xhK2xb6P9wbI2FDKFQoMgCdbjvABF7RRyaEzUoaQ5_Wj53YO6PFYuYcPbqMhdtvSSQiK3Nw6bFer2OfFs6s2RTukRGsocgC5Q7pwQwzYky-YgrPCb-pVAJajVSXUJrayvOi8-TeyCpICW4zTeJa5icZ380cWtafUH4rEB_FOJciJf0BCy48ajbz0NE121uBl2mqA1HE0_mQA53UqVjbrbE9hVOfnN4KpwOfULhIjx54tIekJQgG-aK2AYsLPCDNhuSpHvdwJcTM0Gzy3mS2veyaDV8q2qN5F_F9OThTQzcfy.AXzVNrJc_pGVPsticsVM0w")
    token: uuid;

    @doc("Refresh token.")
+    @format("uuid")


suggestion (non-blocking): I think "jwt" for the format

cassieemb · 2025-07-09T21:26:50Z

specs/signalwire-rest/fabric-api/swml-scripts/addresses/main.tsp

+  @tag("SWML Scripts")
+  interface SWMLScriptAddresses {
+    @summary("List SWML Script Addresses")
+    @doc("A list of SWML Script Addresses. This endpoint uses the bearer token authentication method with the SAT (Subscriber Access Token) which can be generated using the [Create Subscriber Token endpoint](/rest/signalwire-rest/endpoints/fabric/subscriber-tokens-create).")


issue: This endpoint uses basic auth

cassieemb · 2025-07-09T21:27:26Z

specs/signalwire-rest/fabric-api/swml-scripts/models/core.tsp

+
+  @doc("Optional description of the SWML script")
+  @example("Welcome message script")
+  description?: string;


question: I don't think this is a field we have, did you see this somewhere?

cassieemb · 2025-07-09T21:27:48Z

specs/signalwire-rest/fabric-api/swml-webhook/addresses/main.tsp

@@ -13,7 +13,7 @@ namespace FabricAPI.SWMLWebhookAddresses {
  @friendlyName("SWML Webhooks")
  interface SWMLWebhookAddresses {
    @summary("List SWML Webhook Addresses")
-    @doc("A list of SWML Webhook Addresses")
+    @doc("A list of SWML Webhook Addresses. This endpoint uses the bearer token authentication method with the SAT (Subscriber Access Token) which can be generated using the [Create Subscriber Token endpoint](/rest/signalwire-rest/endpoints/fabric/subscriber-tokens-create).")


issue: This endpoint uses basic auth

imfaruk

Looking really great!

Few concerns:

Endpoints of this format api/fabric/resources/{resourceable}/{resource_id}/addresses uses Basic Auth
/api/fabric/addresses uses Bearer Token
Some of the @summary and @doc ends with a full stop(.) others don't. I myself introduced this inconsistency in many places before.

imfaruk · 2025-07-10T10:28:25Z

specs/signalwire-rest/fabric-api/freeswitch-connectors/addresses/main.tsp

+  @tag("FreeSWITCH Connectors")
+  interface FreeswitchConnectorAddresses {
+    @summary("List FreeSWITCH Connector Addresses")
+    @doc("A list of FreeSWITCH Connector Addresses. This endpoint uses the bearer token authentication method with the SAT (Subscriber Access Token) which can be generated using the [Create Subscriber Token endpoint](/rest/signalwire-rest/endpoints/fabric/subscriber-tokens-create).")


I think this endpoint does use basic auth

imfaruk · 2025-07-10T10:54:28Z

specs/signalwire-rest/fabric-api/subscribers/refresh-tokens/models/requests.tsp

@@ -1,5 +1,6 @@
 model SubscriberRefreshTokenRequest {
  @doc("The refresh token previously issued alongside a subscriber access token. This token is used to request a new access token.")
  @example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
-  refresh_token: string;
+  @format("uuid")
+  refresh_token: uuid;


Same concern as Cassie regarding the format

imfaruk · 2025-07-10T10:54:49Z

specs/signalwire-rest/fabric-api/subscribers/refresh-tokens/models/responses.tsp

@@ -1,9 +1,11 @@
 model SubscriberRefreshTokenResponse {
  @doc("A newly generated subscriber access token, valid for 2 hours.")
  @example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
-  token: string;
+  @format("uuid")
+  token: uuid;


Same concern as Cassie regarding the format

imfaruk · 2025-07-10T10:54:54Z

specs/signalwire-rest/fabric-api/subscribers/refresh-tokens/models/responses.tsp


  @doc("A new refresh token, valid for 2 hours and 5 minutes.")
  @example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
-  refresh_token: string;
+  @format("uuid")
+  refresh_token: uuid;


Same concern as Cassie regarding the format

Devon-White added 2 commits July 9, 2025 08:12

Initial push

5eaa076

Convert all Fabric api spec to TypeSpec

a018cf0

Devon-White requested review from briankwest, niravcodes and hey-august as code owners July 9, 2025 19:24

Devon-White added the area/rest-api label Jul 9, 2025

Merge branch 'main' into Devon/fabric-typespec

02ed089

Devon-White changed the title ~~Devon/fabric typespec~~ WIP - Convert Fabric APIs to TypeSpec Jul 9, 2025

Devon-White requested a review from a team July 9, 2025 19:40

cassieemb reviewed Jul 9, 2025

View reviewed changes

Devon-White added 8 commits July 9, 2025 17:53

Merge branch 'main' into Devon/fabric-typespec

8a11399

add newline

f6ba52d

Update main.tsp

7011b0d

Update responses.tsp

0b5ce7b

Update main.tsp

34ac7f2

Update core.tsp

7c9287b

Update errors.tsp

551a212

Update requests.tsp

e78bc80

imfaruk reviewed Jul 10, 2025

View reviewed changes

WIP - Convert Fabric APIs to TypeSpec #373

Are you sure you want to change the base?

WIP - Convert Fabric APIs to TypeSpec #373

Uh oh!

Conversation

Devon-White commented Jul 9, 2025

REST API Update Pull Request

Description

Type of Change

Motivation and Context

Checklist:

Uh oh!

netlify bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for signalwire-docs ready!

Uh oh!

github-actions bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenAPI Specification Analysis

Uh oh!

Devon-White commented Jul 9, 2025

Uh oh!

cassieemb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

imfaruk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

netlify bot commented Jul 9, 2025 •

edited

Loading

github-actions bot commented Jul 9, 2025 •

edited

Loading