Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Show HN: Instant API – Build type-safe web APIs with JavaScript

github.com

Post reply on HN
Print view View original

61–70 of 88 posts

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#61

Post by MrGilbert »

codemusings wrote: post #48

Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think this is superior to using an actual type-safe language like TypeScript? /** * Streams results for our lovable assistant * @param {string} query The question for our assistant * @stream {object} chunk * @stream {string} chunk.id * @stream {string} chunk.object * @stream {integer} chunk.created * @stre…

Side note: "Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think [...]"

It is absolutely possible to question the necessity of a or motivation behind a project, without attacking someone. It's not that OP did ruin a million dollar project. I find your comment quite harsh. Prefacing it with the very first sentence shows that you were quite aware of that. Not a good style, in my opinion.

//Despite the downvotes, I still stand by my opinion. I don't get them, but that's fine.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#62

Post by theryan »

KronisLV wrote: post #47
keithwhor wrote: post #5

Earlier quoted context omitted.

The naming is completely coincidental and probably a little confusing / unfortunate. OpenAPI is a rebranding of Swagger, a really popular open source API specification. Incidentally the OpenAPI initiative only predates OpenAI by a month so I don’t think Sam, Greg & co could have known better at the time. But OpenAPI is the “gold standard” machine readable API specification format so it makes sense that OpenAI would r…

> But OpenAPI is the “gold standard” machine readable API specification format I remember when that would have been WSDL, with something like SoapUI - where you'd feed in the service description file from whatever service you want to interact with and would get a functional API client. It also had codegen that let you end up with full client stubs in Java or another language, or are able to generate the WSDL file fro…

Many years ago I was connecting APIs from ~100 companies into our application, they all essentially did the same thing -- update information in our system based on a tracking number. At this time, about half were web APIs and half were WSDLs. The WSDL APIs were by and large the easiest to work with, I didn't have to write much of any code. On the other hand, the web APIs required me to have a custom flow for each and every one and they could break at any point without me knowing.

I've seen a lot of hate on WSDLs throughout the years but they were honestly really productive for getting work done.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#63

Post by yashap »

w3news wrote: post #58
codemusings wrote: post #48

Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think this is superior to using an actual type-safe language like TypeScript? /** * Streams results for our lovable assistant * @param {string} query The question for our assistant * @stream {object} chunk * @stream {string} chunk.id * @stream {string} chunk.object * @stream {integer} chunk.created * @stre…

It is type safety at runtime. Typescript gives you some type safety at develop time (like jsdoc also can do) But if I read it right, this helps you to generate OpenAPI spec to validate the api endpoints, to get easy type safety at runtime. See also e.g. https://openapistack.co/docs/openapi-backend/intro/ that is also helping to be type safe at runtime. Or Nest can also generate OpenAPI als validation based on it. Onl…

It is worth noting there are good options out there to get both compile time type safety and runtime validation using TypeScript.

Personally I’m a fan of ts-rest: https://ts-rest.com/

Write a specification of your endpoints in TypeScript, and from that one spec you get:

- Server side validation of requests/responses

- A TypeScript API client

- Specialized clients, if you like, for example a react-query client if you like using react-query

- Auto-generated docs (OAS)

- TypeScript types for requests and responses to use in your code

IMO a lot more maintainable than a jsdoc based approach. For example, you can define a type for a Person, and then re-use that type in the responses of all Person-related endpoints, and even in POST/PUT/PATCH bodies (saying things like “the POST body is a person Person, but omit the id field”). With jsdoc you’re repeating that definition a tonne, AND you’re lacking compile time type safety.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#64

Post by mablopoule »

codemusings wrote: post #48

Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think this is superior to using an actual type-safe language like TypeScript? /** * Streams results for our lovable assistant * @param {string} query The question for our assistant * @stream {object} chunk * @stream {string} chunk.id * @stream {string} chunk.object * @stream {integer} chunk.created * @stre…

I don't have an opinion about this particular project, but this just JSDoc, as mentioned in the readme: "Simply write a JSDoc-compliant comment block for a function that represents your API endpoint".

Yes, it's verbose, but its advantages over Typescript is that it work without any compilation step, while being standard enough to give helpful type-hint on any good enough IDE.

Of course, if your project uses Typescript already, you should use Typescript instead, but if you just want to do a simple web page without any compilation step/package.json shenanigan, it's sometime nice to reach for JSDoc.

EDIT: to answer your question, in JSDoc you can typedef your own custom objects[0], so you thankfully don't have to repeat your types everywhere.

[0] https://devhints.io/jsdoc

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#65

Post by 9dev »

ushakov wrote: post #55
9dev wrote: post #53

Earlier quoted context omitted.

Yes, I was wondering about that too. If you put in the effort to parse the docblock into runtime validation, why not pick up the existing utilities to convert TypeScript types into runtime code during the build? That would be much more powerful, with the added benefit of having type safety for all other code, and a familiar syntax for developers.

…or just use Zod?

Yeah, that’s what I was thinking of. There are a few alternatives though, so I referred to existing tooling in general.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#66

Post by keithwhor »

mkl wrote: post #56

I spotted a bug in the README's first example: @param {number{-90,90}} coords.lng Longitude The range for longitude is incorrect, and only covers half the globe. How and when are these kinds of types checked? Would this error only be found at runtime?

Thanks for the tip! Fixed this; just missed this when writing the example.

This error would only be found if you wrote a test for it. The framework doesn't have an AI integration that checks whether or not your types are consistent with real world applications... but could.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#67

Post by r3trohack3r »

jfengel wrote: post #60
codemusings wrote: post #50

Earlier quoted context omitted.

> And no — type safety is applied at the HTTP interface. So it's basically validation middleware. The HTTP protocol does not define any such thing.

No, and neither does Typescript. One of the biggest weaknesses in Typescript is that it can't validate data across the wire. Which is a major use case for the language. There are various tools for it already, but the JS ecosystem has always been up for yet another framework.

I hear you, but I don’t think this is necessarily true. It does leave type checking to your parsing logic, but the compiler can give you strong guarantees that you’re being defensive about untrusted structured data.

I use a JsonObject to do type narrowing and generate appropriate error messages when I receive invalid data over the wire: https://www.npmjs.com/package/@retrohacker/json-types

In every codebase I’ve added this to, I’ve found invalid parsing logic.

I feel like this type, or something similar, should be bundled in the official TypeScript project. That untested data comes out as “any” is not a good developer experience in my opinion.

And “unknown” is basically broken for type narrowing.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#68

Post by ebalit »

keithwhor wrote: post #66
mkl wrote: post #56

I spotted a bug in the README's first example: @param {number{-90,90}} coords.lng Longitude The range for longitude is incorrect, and only covers half the globe. How and when are these kinds of types checked? Would this error only be found at runtime?

Thanks for the tip! Fixed this; just missed this when writing the example. This error would only be found if you wrote a test for it. The framework doesn't have an AI integration that checks whether or not your types are consistent with real world applications... but could.

I know the answer is a bit tongue in cheek, but that would be very valuable and cool, just in case someone from Cursor or Refact is reading this thread ^^

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#69

Post by madeofpalk »

ushakov wrote: post #55
9dev wrote: post #53

Earlier quoted context omitted.

Yes, I was wondering about that too. If you put in the effort to parse the docblock into runtime validation, why not pick up the existing utilities to convert TypeScript types into runtime code during the build? That would be much more powerful, with the added benefit of having type safety for all other code, and a familiar syntax for developers.

…or just use Zod?

I don't like writing type definitions with zod's DSL.

I want to write definitions in the "first party syntax" - which both JSDoc and Typescript types are - and have everything else generated out from that.

Re: Show HN: Instant API – Build type-safe web APIs with JavaScript

#70

Post by madeofpalk »

r3trohack3r wrote: post #67
jfengel wrote: post #60

Earlier quoted context omitted.

No, and neither does Typescript. One of the biggest weaknesses in Typescript is that it can't validate data across the wire. Which is a major use case for the language. There are various tools for it already, but the JS ecosystem has always been up for yet another framework.

I hear you, but I don’t think this is necessarily true. It does leave type checking to your parsing logic, but the compiler can give you strong guarantees that you’re being defensive about untrusted structured data. I use a JsonObject to do type narrowing and generate appropriate error messages when I receive invalid data over the wire: https://www.npmjs.com/package/@retrohacker/json-types In every codebase I’ve adde…

> And “unknown” is basically broken for type narrowing.

How? Typescript 4.9 improved it for type narrowing significantly. https://devblogs.microsoft.com/typescript/announcing-typescr...

Last weekend I actually hacked an an experiment to codegen narrowing unknown to a specific type and it works pretty well https://github.com/joshhunt/codegen-json-validator-experimen...

Post reply on HN