SWAPI with TypeSpec

[connorjs]

Hey y’all - I just wanted to share my first hands-on project with TypeSpec: swapi-typespec (GitHub repo + npm package).

I wanted to build out a REST API with TypeSpec and chose SWAPI (the Star Wars API) for my exploration.

I have previously used Smithy (by AWS), so I’m happy to now have a Smithy-vs-TypeSpec mental comparison.

[bterlson]

This is super cool, thanks for sharing! The TypeSpec looks really good too. May offer some suggestions next week when I get a chance to look more closely.

Can you say more about your experience? Any likes and dislikes? Any feedback would be greatly appreciated.

[connorjs]

Feedback in stream of consciousness order. I may later edit per priorities, but wanted to get notes down ASAP. Thanks for responding!.

• Tooling/syntax highlighting

  • It was easy to install the plugins with the CLI, but it will be nicer to formally release them. Any blockers for that?
  • Specifically, if formally released, maybe “we” could get a JetBrains plugin built. I’m using Rider these days, but have used WebStorm and IntelliJ in the past.
  • If tsp is finalized now (post CADL transition), it would be nice to start adding typespec and tsp to syntax highlighters. I think it makes sense to start with GitHub (plus Microsoft owns both😉)

• Documentation

  • Some of the documentation organization felt out of order. I can provide deeper feedback here if desired. I believe I’ve seen many doc issues/stories, so I know that’s evolving.
  • I found some very good information buried a bit deeper in the specific package documentation (example for http). I don’t know if it should be higher, but I didn’t find some information until my 5th+ read through of the doc site, and only after I first found it by browsing the GitHub repo directly (and later pulling down the repo).
  • I’m happy to take time to submit documentation PRs/share more thoughts if desired.

• TypeSpec Language itself

  • Overall, the ergonomics are nice. I’m coming from AWS where we used Smithy and this was comparable enough. I use the term enough because Smithy felt more polished, which makes sense given TypeSpec pre-release state. It could be personal bias though, or maybe relates to documentation.
  • I have mixed feelings about the keyword/language/term choice of interface and extends given the different constraints and goals of polymorphism over the wire compared to inside an object-oriented application. I also need to understand interfaces better in TypeSpec.
  • I had a mixed experience with templates in SWAPI. These two commits shed some more light on my personal experience.
    • Experiment with templates - See some dev comments for notes
    • Removes template - Commit message has notes
  • That being said, I liked the idea of composition, mixins, templates, etc. Some more experience will help me better choose when and when not to use these constructs

• Configuration

  • I found it odd that options was separate from emit array. I would expect the emit members to be a string (the emitter name) or an object with name + options.
  • It seems that main.tsp is special w.r.t. imports. There were times where I thought I needed imports in other files, but then I could remove them later when main.tsp had them. All files required the using syntax though.
  • nit - Allow .yml extension in addition to .yaml

• Other notes

  • npm/JS/TS-based is a great call imo. It’s lighter-weight and it all runs at build time. Smithy using Java was one of my bigger complaints (e.g. it makes it harder to bring it into a .NET shop). Likewise, JS is better than C#/.NET stack for TypeSpec so it can be used in Java shops (for example).
  • I look forward to linting! That provides a huge value add of the design-first/language-first API approach.
  • I also look forward to codegen, although I believe the plan right now is to generate Open API and rely on the existing ecosystem to codegen from that. I have not yet gotten to my codegen exploration.

To be clear, and in conclusion, I do enjoy TypeSpec. And it has taken the lead in my mind for a design-first API language that I want to introduce in my current work (which is .NET based, so no Java a.k.a. Smithy doesn’t make sense).

[connorjs]

Oh, and the best part of TypeSpec I mentioned in my repo.

The generated Open API 3 specification has 878 lines (with no blank lines) in a single file. The TypeSpec source has 493 lines (about ⅓ are blank lines for readability) split across 8 files for logical organization, which is a ~45% reduction in lines of code.

If we ignore the imports, using statements, and blank lines within models, then the TypeSpec only has 353 lines. That means a 60% reduction in code to maintain.

[markcowl]

@connorjs Thank you for the great feedback!

• On Tooling / syntax highlighting
  • There is a bit of red tape involved in publishing the extensions to the marketplace, but this is the end goal, and we have a backlog issue tracking this
  • There are usage requirements for having the syntax highlighting added to github, but we are tracking this and plan to push this through once the requirements are met
• On documentation
  • This is great feedback, and if you have time for more detailed feedback, we would really appreciate it!
• On TypeSpec Language
  • Thanks for the great feedback!
  • We will soon have support for named parameters in templates, which should make complex templates more usable