Skip to content

WIP - Convert Fabric APIs to TypeSpec #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from

Conversation

Devon-White
Copy link
Contributor

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.

Copy link

netlify bot commented Jul 9, 2025

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...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
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.

Copy link

github-actions bot commented Jul 9, 2025

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 Devon-White changed the title Devon/fabric typespec WIP - Convert Fabric APIs to TypeSpec Jul 9, 2025
@Devon-White Devon-White requested a review from a team July 9, 2025 19:40
@Devon-White
Copy link
Contributor Author

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

Copy link
Contributor

@cassieemb cassieemb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +52 to +79
@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;
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

subscriber_id: uuid;

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@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")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@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).")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: This endpoint uses basic auth


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -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).")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: This endpoint uses basic auth

Copy link
Contributor

@imfaruk imfaruk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@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).")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this endpoint does use basic auth

@@ -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;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same concern as Cassie regarding the format

@@ -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;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same concern as Cassie regarding the format


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same concern as Cassie regarding the format

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants