4 ms·

Goa: Design-First API Generation

99 points by kawera 10y ago

niftich 10y ago
I'm really happy to see this because I hear people talking about using Go to implement microservices, but fewer mentions of what tools they're using to implement them. This looks like a good 'toolkit' to ease the development of such a service. There are also some code examples, e.g. to implement authorization with JWT or OAuth2: https://github.com/goadesign/examples/tree/master/security https://github.com/goadesign/examples/tree/master/security
nathancahill 10y ago
This was/(is?) one of the goals of Swagger[0]. Lots of promises, but have yet to see it work in the wild. I want to use whatever Stripe uses for their API design. [0] http://swagger.io/ http://swagger.io/
- niftich 10y ago
  Yes, Swagger is intended to be a service description in this space. But goa seems to allow you to do your design in their DSL and then generate a Swagger spec from it [1]. [1] http://goa.design/design/swagger/ http://goa.design/design/swagger/
  - nathancahill 10y ago
    We must go deeper.
    - seanp2k2 10y ago
      Todo: write a thing that makes Goa from a RailsAPI server. The goal is to have it be able to generate the same exact RailsAPI code. The usefulness is that a different team not as comfortable with Rails could use the generated Goa code to generate the same RailsAPI server in the language they're comfortable working with, make their contributions, and have that generate new Goa, which the first team would use to generate the updated RailsAPI code. Kind of a Rosetta Stone for APIs, but only useful if it works both ways, picks up every small change in exacting detail, and works server ->spec ->same server. Not sure if that's even possible, but it'd be cool.
      - nathancahill 10y ago
        Have you seen this? https://github.com/mame/quine-relay https://github.com/mame/quine-relay
- supergeek133 10y ago
  https://github.com/lord/slate https://github.com/lord/slate
- hakanito 10y ago
  https://readme.io https://readme.io
cakoose 10y ago
Both Swagger and Goa can generate API client code from their respective spec languages. Goa additionally has the ability to generate a Swagger spec from a Goa spec. This makes me wonder why Goa just doesn't rely on the Swagger code generators? Are they not very good? The Goa page talks about generating Swagger so you can use the Swagger doc generator. Maybe that's the only part of Swagger that the Goa developers think is useful? Also, Swagger has more traction right now. Maybe the ability to generate a Swagger spec lets people not feel so locked in to Goa, the newcomer?
- niftich 10y ago
  They approach the same problem from opposite directions. Goa's DSL will let you code a server, and then export a Swagger spec that clients can consume (and codegen their end from). Whereas Swagger's code generators start with the Swagger spec already written. You can use them to generate a server, which will create the scaffolding but leave you with the logic to implement.
  - tokenizerrr 10y ago
    Swagger can also generate its spec from an already written server, and that's how I'm using it primarily.
    - niftich 10y ago
      Would you mind linking to some docs on how to do that? I only found this quote, which hints that it's a manual process (if your framework doesn't produce the spec): "Either you create the definition manually (using the same Swagger Editor mentioned above), or if you are using one of the supported frameworks (JAX-RS, node.js, etc) [1], you can get the Swagger definition generated automatically for you." [2] [1] http://swagger.io/open-source-integrations/ http://swagger.io/open-source-integrations/ [2] http://swagger.io/getting-started/ http://swagger.io/getting-started/
      - tokenizerrr 10y ago
int_handler 10y ago
Which font is the one used in the first few editor screenshots on the Goa site?
- libria 10y ago
  Pretty sure it's PragmataPro. Dotted zero's, very thin 'm', looptail 'g'.
zghst 10y ago
I've been looking for the Google open source beta version of this. It's been killing me that I can't remember what it's called... I believe it's done in either C++ or Golang, green/white home page
- buckhx 10y ago
  GRPC? Not the same, but allows you to specify the API in a static file and generate native language clients among many other things.
  - kawera 10y ago
    http://www.grpc.io/ http://www.grpc.io/ https://github.com/grpc/grpc https://github.com/grpc/grpc https://developers.googleblog.com/2015/02/introducing-grpc-new-open-source-http2.html https://developers.googleblog.com/2015/02/introducing-grpc-n...
bketelsen 10y ago
The creator of goa is presenting on code generation and APIs at Gophercon this year. I'm also presenting on goa at abstractions.io in August. I'm quite biased as a contributor, but I think goa is a great solution for APIs because it encourages you to think through the design completely and generates the code from that design. Generated code is idiomatic and clean. You can see me present at the Tampa Go Meetup here: https://www.youtube.com/watch?v=tCFrgWikEX8 https://www.youtube.com/watch?v=tCFrgWikEX8
- thinxer 10y ago
  How does this compares to gRPC which has many languages supported already?
  - bketelsen 10y ago
    gRPC is a great framework for generating RPC servers and clients, it's a different space. goa is built for creating an entire REST API.

99 points by kawera 10y ago

I'm really happy to see this because I hear people talking about using Go to implement microservices, but fewer mentions of what tools they're using to implement them. This looks like a good 'toolkit' to ease the development of such a service. There are also some code examples, e.g. to implement authorization with JWT or OAuth2: https://github.com/goadesign/examples/tree/master/security https://github.com/goadesign/examples/tree/master/security

nathancahill 10y ago

This was/(is?) one of the goals of Swagger[0]. Lots of promises, but have yet to see it work in the wild. I want to use whatever Stripe uses for their API design. [0] http://swagger.io/ http://swagger.io/

niftich 10y ago
Yes, Swagger is intended to be a service description in this space. But goa seems to allow you to do your design in their DSL and then generate a Swagger spec from it [1]. [1] http://goa.design/design/swagger/ http://goa.design/design/swagger/
- nathancahill 10y ago
  We must go deeper.
  - seanp2k2 10y ago
    Todo: write a thing that makes Goa from a RailsAPI server. The goal is to have it be able to generate the same exact RailsAPI code. The usefulness is that a different team not as comfortable with Rails could use the generated Goa code to generate the same RailsAPI server in the language they're comfortable working with, make their contributions, and have that generate new Goa, which the first team would use to generate the updated RailsAPI code. Kind of a Rosetta Stone for APIs, but only useful if it works both ways, picks up every small change in exacting detail, and works server ->spec ->same server. Not sure if that's even possible, but it'd be cool.
    - nathancahill 10y ago
      Have you seen this? https://github.com/mame/quine-relay https://github.com/mame/quine-relay
supergeek133 10y ago
https://github.com/lord/slate https://github.com/lord/slate
hakanito 10y ago
https://readme.io https://readme.io

cakoose 10y ago

Both Swagger and Goa can generate API client code from their respective spec languages. Goa additionally has the ability to generate a Swagger spec from a Goa spec. This makes me wonder why Goa just doesn't rely on the Swagger code generators? Are they not very good? The Goa page talks about generating Swagger so you can use the Swagger doc generator. Maybe that's the only part of Swagger that the Goa developers think is useful? Also, Swagger has more traction right now. Maybe the ability to generate a Swagger spec lets people not feel so locked in to Goa, the newcomer?

niftich 10y ago
They approach the same problem from opposite directions. Goa's DSL will let you code a server, and then export a Swagger spec that clients can consume (and codegen their end from). Whereas Swagger's code generators start with the Swagger spec already written. You can use them to generate a server, which will create the scaffolding but leave you with the logic to implement.
- tokenizerrr 10y ago
  Swagger can also generate its spec from an already written server, and that's how I'm using it primarily.
  - niftich 10y ago
    Would you mind linking to some docs on how to do that? I only found this quote, which hints that it's a manual process (if your framework doesn't produce the spec): "Either you create the definition manually (using the same Swagger Editor mentioned above), or if you are using one of the supported frameworks (JAX-RS, node.js, etc) [1], you can get the Swagger definition generated automatically for you." [2] [1] http://swagger.io/open-source-integrations/ http://swagger.io/open-source-integrations/ [2] http://swagger.io/getting-started/ http://swagger.io/getting-started/
    - tokenizerrr 10y ago

int_handler 10y ago

Which font is the one used in the first few editor screenshots on the Goa site?

libria 10y ago
Pretty sure it's PragmataPro. Dotted zero's, very thin 'm', looptail 'g'.

zghst 10y ago

I've been looking for the Google open source beta version of this. It's been killing me that I can't remember what it's called... I believe it's done in either C++ or Golang, green/white home page

buckhx 10y ago
GRPC? Not the same, but allows you to specify the API in a static file and generate native language clients among many other things.
- kawera 10y ago
  http://www.grpc.io/ http://www.grpc.io/ https://github.com/grpc/grpc https://github.com/grpc/grpc https://developers.googleblog.com/2015/02/introducing-grpc-new-open-source-http2.html https://developers.googleblog.com/2015/02/introducing-grpc-n...

bketelsen 10y ago

The creator of goa is presenting on code generation and APIs at Gophercon this year. I'm also presenting on goa at abstractions.io in August. I'm quite biased as a contributor, but I think goa is a great solution for APIs because it encourages you to think through the design completely and generates the code from that design. Generated code is idiomatic and clean. You can see me present at the Tampa Go Meetup here: https://www.youtube.com/watch?v=tCFrgWikEX8 https://www.youtube.com/watch?v=tCFrgWikEX8

thinxer 10y ago
How does this compares to gRPC which has many languages supported already?
- bketelsen 10y ago
  gRPC is a great framework for generating RPC servers and clients, it's a different space. goa is built for creating an entire REST API.