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	`1c1584d`
🔍 Latest deploy log	https://app.netlify.com/projects/signalwire-docs/deploys/68791f9cedb5e80009c45cab
😎 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: 32 (🟢 up 6 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`	99/100 (+4.0) 🟢	99/100 (+7.0) 🟢	100/100 (+4.0) 🟢	84/100 (+32.0) 🟢	95/100 (+11.0) 🟢	557 (+232) 🔴	2 (-91) 🟢	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.43s.

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

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

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

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

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

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

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

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

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.

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

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

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

…odels/core.tsp Co-authored-by: Cassie <[email protected]>

- Introduced Ciphers enum with various AES cipher options. - Added Codecs enum for audio and video codecs including PCMU, PCMA, G722, G729, OPUS, VP8, and H264. - Created Encryption enum to define encryption requirements: Required, Optional, and Default.

…/docs into Devon/fabric-typespec

* Add status callback fields to CXML and SWML Scripts endpoints * Update core.tsp * Update specs/signalwire-rest/fabric-api/cxml-scripts/models/requests.tsp * Update specs/signalwire-rest/fabric-api/cxml-scripts/models/requests.tsp * Update specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp * Update specs/signalwire-rest/fabric-api/swml-scripts/models/requests.tsp --------- Co-authored-by: Devon <[email protected]>

cassieemb

I think this looks great, really nice work with this!! I'm a big fan of how you organized the documentation as well, it's a very clean look.

I have a few nits but 99.9% of them are missing new lines, so hopefully that's easy to update across all of them at once! 😅

The missing new lines can cause problems in prime, but if it doesn't for Docusaurus, let me know and I'm happy to approve without those changes.

My one thought is that it could be helpful if we put SWML Scripts and SWML Webhooks together here, like you did with all the CXML resource types. However, I wouldn't block on this!

specs/signalwire-rest/_globally_shared/enums.tsp

specs/signalwire-rest/fabric-api/_shared/const.tsp

specs/signalwire-rest/fabric-api/call-flows/models/responses.tsp

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

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

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

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

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

…ests.tsp Co-authored-by: Cassie <[email protected]>

….tsp Co-authored-by: Cassie <[email protected]>

…ests.tsp Co-authored-by: Cassie <[email protected]>

…onses.tsp Co-authored-by: Cassie <[email protected]>

Devon-White · 2025-07-17T16:00:49Z

I think this looks great, really nice work with this!! I'm a big fan of how you organized the documentation as well, it's a very clean look.

I have a few nits but 99.9% of them are missing new lines, so hopefully that's easy to update across all of them at once! 😅

The missing new lines can cause problems in prime, but if it doesn't for Docusaurus, let me know and I'm happy to approve without those changes.

My one thought is that it could be helpful if we put SWML Scripts and SWML Webhooks together here, like you did with all the CXML resource types. However, I wouldn't block on this!

It seems TypeSpec actually doesnt care for newlines.

I was curious to see if their formatter would fix this for us automatically: https://typespec.io/docs/handbook/formatter/

Testing this in the SWML schema repo, i found it actively removes them when present:

I think we are good to ignore newlines in this case, however, if we wanted to add a code style rule to include newlines so we are consistent with your rules, we can add a custom linter: https://typespec.io/docs/extending-typespec/linters/

cassieemb · 2025-07-17T16:03:02Z

I think this looks great, really nice work with this!! I'm a big fan of how you organized the documentation as well, it's a very clean look.
I have a few nits but 99.9% of them are missing new lines, so hopefully that's easy to update across all of them at once! 😅
The missing new lines can cause problems in prime, but if it doesn't for Docusaurus, let me know and I'm happy to approve without those changes.
My one thought is that it could be helpful if we put SWML Scripts and SWML Webhooks together here, like you did with all the CXML resource types. However, I wouldn't block on this!

It seems TypeSpec actually doesnt care for newlines.

I was curious to see if their formatter would fix this for us automatically: https://typespec.io/docs/handbook/formatter/

Testing this in the SWML schema repo, i found it actively removes them when present:
I think we are good to ignore newlines in this case, however, if we wanted to add a code style rule to include newlines so we are consistent with your rules, we can add a custom linter: https://typespec.io/docs/extending-typespec/linters/

Sounds good to me! I will resolve all the new line comments

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

Devon-White and others added 8 commits July 11, 2025 17:20

Push audit edits (in-progress)

8cae635

Push audit edits (in-progress)

6684162

Update specs/signalwire-rest/fabric-api/dialogflow-agents/addresses/m…

daf59c6

…odels/core.tsp Co-authored-by: Cassie <[email protected]>

Merge branch 'Devon/fabric-typespec' of https://github.com/signalwire…

29eaa76

…/docs into Devon/fabric-typespec

Merge branch 'main' into Devon/fabric-typespec

8c4a9cd

edits

d09a11d

Merge branch 'Devon/fabric-typespec' of https://github.com/signalwire…

40b1241

…/docs into Devon/fabric-typespec

Devon-White and others added 7 commits July 16, 2025 17:01

Fix bad summary

9958b36

Conference Room edits

3910d85

add missing fps property to conference rooms

0761904

Merge branch 'main' into Devon/fabric-typespec

009d58c

Merge branch 'main' into Devon/fabric-typespec

3eac605

Add redirects

7eb40aa

Merge branch 'Devon/fabric-typespec' of https://github.com/signalwire…

090f1ee

…/docs into Devon/fabric-typespec

Devon-White changed the title ~~WIP - Convert Fabric APIs to TypeSpec~~ Convert Fabric APIs to TypeSpec Jul 17, 2025

diego-signalwire and others added 2 commits July 17, 2025 08:38

recompile spec after additions

0c44189

briankwest previously approved these changes Jul 17, 2025

View reviewed changes

cassieemb reviewed Jul 17, 2025

View reviewed changes

Update specs/signalwire-rest/fabric-api/cxml-applications/models/requ…

3453b74

…ests.tsp Co-authored-by: Cassie <[email protected]>

Devon-White dismissed briankwest’s stale review via 3453b74 July 17, 2025 15:40

Devon-White and others added 6 commits July 17, 2025 11:41

Update specs/signalwire-rest/fabric-api/cxml-applications/models/core…

db0d1ff

….tsp Co-authored-by: Cassie <[email protected]>

Update specs/signalwire-rest/fabric-api/cxml-applications/models/core…

a061bab

….tsp Co-authored-by: Cassie <[email protected]>

Update specs/signalwire-rest/fabric-api/cxml-applications/models/requ…

ad6c99d

…ests.tsp Co-authored-by: Cassie <[email protected]>

Update specs/signalwire-rest/fabric-api/cxml-applications/models/requ…

f58a2f2

…ests.tsp Co-authored-by: Cassie <[email protected]>

Update specs/signalwire-rest/fabric-api/cxml-applications/models/resp…

573ebae

…onses.tsp Co-authored-by: Cassie <[email protected]>

Update specs/signalwire-rest/fabric-api/cxml-applications/models/resp…

2053e92

…onses.tsp Co-authored-by: Cassie <[email protected]>

Devon-White added 3 commits July 17, 2025 12:05

Ran TypeSpec formatter

663975e

Ran formatter, and recompiled spec

afcdddd

Ran formatter, and recompiled spec

1c1584d

cassieemb approved these changes Jul 17, 2025

View reviewed changes

briankwest self-requested a review July 17, 2025 17:08

briankwest approved these changes Jul 17, 2025

View reviewed changes

Devon-White merged commit 6e17a94 into main Jul 17, 2025
6 checks passed

Devon-White deleted the Devon/fabric-typespec branch July 17, 2025 17:09

Convert Fabric APIs to TypeSpec #373

Convert Fabric APIs to TypeSpec #373

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

imfaruk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cassieemb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Devon-White commented Jul 17, 2025

Uh oh!

cassieemb commented Jul 17, 2025

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Jul 9, 2025 •

edited

Loading

github-actions bot commented Jul 9, 2025 •

edited

Loading