8 ms·

RESTyped: End-To-end Typing for REST APIs with TypeScript

91 points by rawrmaan 9y ago

jpmoyn 9y ago
I'm a developer at Habitat (the company mentioned in the article), and have been loving working with RESTyped so far. This has saved me so much time that I would usually spend debugging. It's really nice knowing what you should be passing to an endpoint as you type it. If every API I worked with was RESTyped, life would be a dream.
- pjmlp 9y ago
  In a way it is ironic how with Swagger, RESTtyped we are getting back to IDLs and WSDL. Maybe old dogs did understand a few things about doing distributed programming.
  - rawrmaan 9y ago
    Yup. Someone on Reddit suggested making an OpenAPI/Swagger -> RESTyped adapter. If people are interested in this, I'm all for it.
    - oneweekwonder 9y ago
      > Someone on Reddit Got a link to the thread?
      - rawrmaan 9y ago
        https://www.reddit.com/r/programming/comments/7k1zrh/introducing_restyped_endtoend_typing_for_rest/draxi0q/ https://www.reddit.com/r/programming/comments/7k1zrh/introdu...
  - jessaustin 9y ago
    It may be hoped that the next incarnation of this will deal with change better. It's really not enough to just deface every URL with a "/v2/" at the front. That way lies the madness that soured everyone on the great "web services" vision the first time around.
  - Roboprog 9y ago
    God I hate SOAP. Creating a client for WS-Deathstar was always an adventure. The types are defined, so no need for documentation to explain the semantics. Oh, and if you don’t have the same tool stack, good luck getting the envelope header the way our server wants it. Sometimes, there’s value in being able to add or omit attributes without some brittle (static) monstrosity messing itself.
- RubenSandwich 9y ago
  Your link to the definition file, https://blog.falcross.com/introducing-restyped-end-to-end-typing-for-rest-apis-with-typescript/(https:/github.com/rawrmaan/restyped/#specification) https://blog.falcross.com/introducing-restyped-end-to-end-ty..., is 404ing.
  - rawrmaan 9y ago
    Fixed, thank you!
mythz 9y ago
We also support effortless end-to-end Typed API support in ServiceStack: http://docs.servicestack.net/typescript-add-servicestack-reference http://docs.servicestack.net/typescript-add-servicestack-ref... We're a strong believer in TypeScript which we've configured in all our .NET Core 2.0 / .NET Framework Single Page App project templates: http://docs.servicestack.net/releases/v5.0.0#new-net-core-20-and-net-framework-project-templates http://docs.servicestack.net/releases/v5.0.0#new-net-core-20...
filleokus 9y ago
We have been using GraphQL for almost a year now and I'm really pleased with it. In my mind it both solves the type issue, while also providing great flexibility in what data to fetch. I guess this could be used to improve an existing REST API without the big cost of moving to GraphQL (which might even be impossible sometimes). Maybe there are also some situations where GraphQL fails, I would definitely be interested to hear about that.
- WorldMaker 9y ago
  One of my complaints with GraphQL (as an observer; I've not yet directly worked with GraphQL) is that while it has a bunch of type information, most of that is fairly opaque to Typescript itself: queries themselves are mostly opaque strings, and most examples I've seen of query usage (and this may be mostly just a problem with wild examples as opposed to real usage) most of them just use the result of a query call as any-typed, manual type assertion, or manual generic argument to the query call. It seems to me that all of GraphQL's type information should be easier to use in Typescript. I have noticed there is a compiler of .graphql files to .d.ts files [1], and I could see using something like that the way that RESTyped is used in the article here (though it's "backwards" from the RESTyped model where the Typescript definitions are the source of truth [2]), but at least in examples I've seen to date of GraphQL in the wild it does seem like there is a similar need in the GraphQL world for something like RESTyped. [1] https://www.npmjs.com/package/graphql-typescript-definitions https://www.npmjs.com/package/graphql-typescript-definitions [2] Which leads me to wondering if it would be nice to have a Typescript Definition file to GraphQL compiler.
  - lewisl9029 9y ago
    If you use Apollo as your GraphQL client, there's apollo-codegen [0], which supports generating both Flow and TypeScript type definitions. Relay Modern's query compiler also generates Flow types AFAIK. But that's only for the client side. I suppose if you'd like to use typed JavaScript on the server side, something like the library you've posted might be your best bet, since client side solutions like apollo-codegen generate types based on the exact set of queries in your client-side app, which might not be all that useful for implementing the GraphQL server itself (unless maybe your API is private and you can afford to implement some form of persisted queries?). Having access to all the individual base types specified in your schema would probably be more useful for that purpose. [0] https://github.com/apollographql/apollo-codegen https://github.com/apollographql/apollo-codegen
ralmidani 9y ago
I am a Python (Django) and CoffeeScript (with Ember) fan who really wants to learn TypeScript. I already use VSCode. This project looks very promising for building full-stack apps spanning Node and the browser. One thing I would love to see eventually is a reduction in the need for manually pulling attributes from the request body and parsing query params. Does this provide a foundation for building a frictionless end-to-end experience via data adapters (which have served me well in Django/Ember projects, despite some mismatches)?
oalbertini 9y ago
+1 for adding OpenAPI integration
petilon 9y ago
Can't you already do this using Swagger Codegen? I use swashbuckle to automatically generate swagger https://www.nuget.org/packages/Swashbuckle/ https://www.nuget.org/packages/Swashbuckle/ Then paste swagger definition into the online editor to generate TypeScript client: https://swagger.io/swagger-editor/ https://swagger.io/swagger-editor/ (You can also generate offline). How is RESTyped better than Swagger Codgen?
- rawrmaan 9y ago
  This is pretty cool, I hadn't seen it before! RESTyped has a couple of advantages over this: - RESTyped definitions are extremely lightweight and don't require shipping an API wrapper with a bunch of generated code - No build/manual copy step required. Easy to distribute typings on NPM.
  - petilon 9y ago
    Swagger is a de facto standard for automatically generating JSON descriptions of REST API and for generating UI for invoking/experimenting with REST APIs. Swagger codegen is good but not terrific. Alternatives would be welcome. I recommend layering your code gen over swagger.
    - daotoad 9y ago
      Swagger is the basis and a great implementation of OpenAPI which is a standard. https://www.openapis.org https://www.openapis.org
  - kevinoid 9y ago
    I don't understand the advantages, could you clarify? - In what way are RESTyped definitions lighter? A Swagger definition is just a JSON or YAML file and can be used without shipping any additional code (e.g. by https://github.com/swagger-api/swagger-js https://github.com/swagger-api/swagger-js). - Swagger only requires a build step when the definition is used to generate code. Definitions can be distributed via NPM (e.g. https://www.npmjs.com/package/appveyor-swagger https://www.npmjs.com/package/appveyor-swagger). Edit: I realized you were talking about RESTyped being lighter/nobuild compared to Swagger Codegen specifically for TypeScript because it is written in TypeScript. Seems reasonable.
quantumofmalice 9y ago
Allow me to be a bit autistic here: these APIs are barely REST-ful. They are effectively RPC, which is appropriate, because REST doesn't easily apply to a non-hypertext data format, which disallows HATEOAS. I wish XML-RPC hadn't ruined things so utterly, so we could properly refer to these APIs as JSON-RPC and leave REST for hypertext-based architectures (e.g. intercooler.js + html)
styfle 9y ago
I’ll have to give this a go. I usually shared types from the backend to the front end in the same repo. Then change (data: any) To something like (data: User) See this repo https://github.com/styfle/react-server-example-tsx https://github.com/styfle/react-server-example-tsx

91 points by rawrmaan 9y ago

I'm a developer at Habitat (the company mentioned in the article), and have been loving working with RESTyped so far. This has saved me so much time that I would usually spend debugging. It's really nice knowing what you should be passing to an endpoint as you type it. If every API I worked with was RESTyped, life would be a dream.

pjmlp 9y ago
In a way it is ironic how with Swagger, RESTtyped we are getting back to IDLs and WSDL. Maybe old dogs did understand a few things about doing distributed programming.
- rawrmaan 9y ago
  Yup. Someone on Reddit suggested making an OpenAPI/Swagger -> RESTyped adapter. If people are interested in this, I'm all for it.
  - oneweekwonder 9y ago
    > Someone on Reddit Got a link to the thread?
    - rawrmaan 9y ago
      https://www.reddit.com/r/programming/comments/7k1zrh/introducing_restyped_endtoend_typing_for_rest/draxi0q/ https://www.reddit.com/r/programming/comments/7k1zrh/introdu...
- jessaustin 9y ago
  It may be hoped that the next incarnation of this will deal with change better. It's really not enough to just deface every URL with a "/v2/" at the front. That way lies the madness that soured everyone on the great "web services" vision the first time around.
- Roboprog 9y ago
  God I hate SOAP. Creating a client for WS-Deathstar was always an adventure. The types are defined, so no need for documentation to explain the semantics. Oh, and if you don’t have the same tool stack, good luck getting the envelope header the way our server wants it. Sometimes, there’s value in being able to add or omit attributes without some brittle (static) monstrosity messing itself.
RubenSandwich 9y ago
Your link to the definition file, https://blog.falcross.com/introducing-restyped-end-to-end-typing-for-rest-apis-with-typescript/(https:/github.com/rawrmaan/restyped/#specification) https://blog.falcross.com/introducing-restyped-end-to-end-ty..., is 404ing.
- rawrmaan 9y ago
  Fixed, thank you!

mythz 9y ago

We also support effortless end-to-end Typed API support in ServiceStack: http://docs.servicestack.net/typescript-add-servicestack-reference http://docs.servicestack.net/typescript-add-servicestack-ref... We're a strong believer in TypeScript which we've configured in all our .NET Core 2.0 / .NET Framework Single Page App project templates: http://docs.servicestack.net/releases/v5.0.0#new-net-core-20-and-net-framework-project-templates http://docs.servicestack.net/releases/v5.0.0#new-net-core-20...

filleokus 9y ago

We have been using GraphQL for almost a year now and I'm really pleased with it. In my mind it both solves the type issue, while also providing great flexibility in what data to fetch. I guess this could be used to improve an existing REST API without the big cost of moving to GraphQL (which might even be impossible sometimes). Maybe there are also some situations where GraphQL fails, I would definitely be interested to hear about that.

WorldMaker 9y ago
One of my complaints with GraphQL (as an observer; I've not yet directly worked with GraphQL) is that while it has a bunch of type information, most of that is fairly opaque to Typescript itself: queries themselves are mostly opaque strings, and most examples I've seen of query usage (and this may be mostly just a problem with wild examples as opposed to real usage) most of them just use the result of a query call as any-typed, manual type assertion, or manual generic argument to the query call. It seems to me that all of GraphQL's type information should be easier to use in Typescript. I have noticed there is a compiler of .graphql files to .d.ts files [1], and I could see using something like that the way that RESTyped is used in the article here (though it's "backwards" from the RESTyped model where the Typescript definitions are the source of truth [2]), but at least in examples I've seen to date of GraphQL in the wild it does seem like there is a similar need in the GraphQL world for something like RESTyped. [1] https://www.npmjs.com/package/graphql-typescript-definitions https://www.npmjs.com/package/graphql-typescript-definitions [2] Which leads me to wondering if it would be nice to have a Typescript Definition file to GraphQL compiler.
- lewisl9029 9y ago
  If you use Apollo as your GraphQL client, there's apollo-codegen [0], which supports generating both Flow and TypeScript type definitions. Relay Modern's query compiler also generates Flow types AFAIK. But that's only for the client side. I suppose if you'd like to use typed JavaScript on the server side, something like the library you've posted might be your best bet, since client side solutions like apollo-codegen generate types based on the exact set of queries in your client-side app, which might not be all that useful for implementing the GraphQL server itself (unless maybe your API is private and you can afford to implement some form of persisted queries?). Having access to all the individual base types specified in your schema would probably be more useful for that purpose. [0] https://github.com/apollographql/apollo-codegen https://github.com/apollographql/apollo-codegen

ralmidani 9y ago

I am a Python (Django) and CoffeeScript (with Ember) fan who really wants to learn TypeScript. I already use VSCode. This project looks very promising for building full-stack apps spanning Node and the browser. One thing I would love to see eventually is a reduction in the need for manually pulling attributes from the request body and parsing query params. Does this provide a foundation for building a frictionless end-to-end experience via data adapters (which have served me well in Django/Ember projects, despite some mismatches)?

oalbertini 9y ago

+1 for adding OpenAPI integration

petilon 9y ago

Can't you already do this using Swagger Codegen? I use swashbuckle to automatically generate swagger https://www.nuget.org/packages/Swashbuckle/ https://www.nuget.org/packages/Swashbuckle/ Then paste swagger definition into the online editor to generate TypeScript client: https://swagger.io/swagger-editor/ https://swagger.io/swagger-editor/ (You can also generate offline). How is RESTyped better than Swagger Codgen?

rawrmaan 9y ago
This is pretty cool, I hadn't seen it before! RESTyped has a couple of advantages over this: - RESTyped definitions are extremely lightweight and don't require shipping an API wrapper with a bunch of generated code - No build/manual copy step required. Easy to distribute typings on NPM.
- petilon 9y ago
  Swagger is a de facto standard for automatically generating JSON descriptions of REST API and for generating UI for invoking/experimenting with REST APIs. Swagger codegen is good but not terrific. Alternatives would be welcome. I recommend layering your code gen over swagger.
  - daotoad 9y ago
    Swagger is the basis and a great implementation of OpenAPI which is a standard. https://www.openapis.org https://www.openapis.org
- kevinoid 9y ago
  I don't understand the advantages, could you clarify? - In what way are RESTyped definitions lighter? A Swagger definition is just a JSON or YAML file and can be used without shipping any additional code (e.g. by https://github.com/swagger-api/swagger-js https://github.com/swagger-api/swagger-js). - Swagger only requires a build step when the definition is used to generate code. Definitions can be distributed via NPM (e.g. https://www.npmjs.com/package/appveyor-swagger https://www.npmjs.com/package/appveyor-swagger). Edit: I realized you were talking about RESTyped being lighter/nobuild compared to Swagger Codegen specifically for TypeScript because it is written in TypeScript. Seems reasonable.

quantumofmalice 9y ago

Allow me to be a bit autistic here: these APIs are barely REST-ful. They are effectively RPC, which is appropriate, because REST doesn't easily apply to a non-hypertext data format, which disallows HATEOAS. I wish XML-RPC hadn't ruined things so utterly, so we could properly refer to these APIs as JSON-RPC and leave REST for hypertext-based architectures (e.g. intercooler.js + html)

styfle 9y ago

I’ll have to give this a go. I usually shared types from the backend to the front end in the same repo. Then change (data: any) To something like (data: User) See this repo https://github.com/styfle/react-server-example-tsx https://github.com/styfle/react-server-example-tsx