
RESTyped: End-To-end Typing for REST APIs with TypeScript - rawrmaan
https://blog.falcross.com/introducing-restyped-end-to-end-typing-for-rest-apis-with-typescript/
======
petilon
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
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
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
Swagger is the basis and a great implementation of OpenAPI which is a
standard.

[https://www.openapis.org](https://www.openapis.org)

------
quantumofmalice
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)

------
ralmidani
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)?

------
filleokus
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
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
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)

~~~
WorldMaker
Yes, that's the big thing I've been seeing: it's definitely the server-side
story that seems somewhat deficient right now, in terms of end-to-end types.
It does seem like a server built with Typescript should be able to save a lot
of manual GraphQL writing work and reuse a bunch of Typescript type
information, but I don't feel like I've seen a lot of examples and/or
libraries of people doing that.

------
mythz
We also support effortless end-to-end Typed API support in ServiceStack:
[http://docs.servicestack.net/typescript-add-servicestack-
ref...](http://docs.servicestack.net/typescript-add-servicestack-reference)

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...](http://docs.servicestack.net/releases/v5.0.0#new-net-core-20-and-
net-framework-project-templates)

------
styfle
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)

------
jpmoyn
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
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
Yup. Someone on Reddit suggested making an OpenAPI/Swagger -> RESTyped
adapter. If people are interested in this, I'm all for it.

~~~
oneweekwonder
> Someone on Reddit

Got a link to the thread?

~~~
rawrmaan
[https://www.reddit.com/r/programming/comments/7k1zrh/introdu...](https://www.reddit.com/r/programming/comments/7k1zrh/introducing_restyped_endtoend_typing_for_rest/draxi0q/)

------
oalbertini
+1 for adding OpenAPI integration

