6 ms·
Show HN: Given an API, Generate client libraries in Node, Python, PHP, Ruby
PS: Assuming a REST architecture.
- sunkarapk 13y agoAuthor here. I covered almost everything in the documentation. And there is also a small example which is hosted at https://github.com/alpaca-api https://github.com/alpaca-api. Please ask if you have any questions. Thanks
- htuao 13y agoHow do you differ from Swagger, Blueprint, I/O Docs, RAML and all these API endpoint descriptions?
- sunkarapk 13y agoI tried searching for a program which generates client libraries in different programming languages and failed. Could you please link if something does it? From what I gather, the above mentioned sites only provide methods of describing the API and/or Automating the API on the server side. Nothing is said about client libraries. Thanks
- mattdawson 13y agohttp://thrift.apache.org/ http://thrift.apache.org/
- jerf 13y agoI think that creates an API, then exposes it in numerous languages. This writes wrappers to existing APIs. Not the same thing. (Lots of code similarity under the hood, though.)
- mattdawson 13y agoNo, it actually does both - which is why I was so interested in it initially. from the above link: "generates code to be used to easily build RPC clients and servers" TBF, I haven't used it as a developer, but I did contract work with a company that had invested in it heavily. From what I saw of their workflow, it ended up being a pretty nice bootstrap tool and little more. edit: Oh, I see what you're saying. Yes, you're correct - thrift does not wrap existing APIs.
- michaelmior 13y agoWhy create a new format for describing APIs instead of using something like RAML? The client library generation is very useful, but it would be nice if there wasn't yet another format needed to describe the API.
- matt_kantor 13y agohttps://github.com/wordnik/swagger-codegen https://github.com/wordnik/swagger-codegen
- fzltrp 13y agoThere's this utility called swig(http://www.swig.org/ http://www.swig.org/) which let you create wrappers for C/C++ libraries to a number of different target languages (dynamic and static), though often time languages offer ffi on their own. The code generated by this tool is rather heavy weight though. Also I'm not quite sure if this is what you're looking for.
- fehguy 13y agohttps://github.com/wordnik/swagger-codegen https://github.com/wordnik/swagger-codegen does javascript, scala, java, objective-c, php, python (3), ruby, android, and even flash Also has the benefit of a commercial backer (https://helloreverb.com https://helloreverb.com) and a real app depending on it
- rybosome 13y agoHey, I noticed you mentioned that you were interested in having client library generation in Obj-C, Java, and Scala, yet all of the existing client lib support is for dynamic languages. I think you may find that some fundamental changes need to be made to support this, unless every datatype is just going to be a string.
- sunkarapk 13y agoIf you are talking about API definition, there need not be many changes since api.json do not define any objects. If you are talking about the code of the program, they wont be changed because, the program just compiles and executes the templates. If I didnt answer your question properly, could you please elaborate?
- johnnyio 13y agoDescribing an API is not hard, but the API authentication method is. How do you think you will do it? Edit : If you don't make oauth consumption simpler, you don't really solve the problem
- sunkarapk 13y agoCurrently, I am supporting 3 authentication strategies. Basic, Token in header and OAUTH. These will cover most of the APIs. And I am open to include other kind of authentication strategies too. https://github.com/pksunkara/alpaca#authorization-strategies https://github.com/pksunkara/alpaca#authorization-strategies EDIT: OAUTH Consumption is not the main priority here. The problem I intended to solve is automating the development and maintaing of API client libraries in several different languages. That said, I intend to add support for OAUTH consumption too.
- pjmlp 13y agoCan we please stop calling Web Services APIs?
- mikekekeke 13y agoAm I right in thinking about this like a WSDL, but based on JSON?
- sunkarapk 13y agoBeing a WSDL is not the aim here. Generating client libraries in multiple programming languages is. But, to do that I need a format using which people can define their API. I used JSON and only supported the elements that I needed to generate the client libraries.
- mikekekeke 13y agoRight, the format affords generic description documents from which to generate client code. This seems very similar in spirit to WSDL. No?
- boomlinde 13y agoWSDL is not a method in itself for actually generating the client code, though. It's simply a (barely) machine readable description of the API from which clients decide how to deal with it. EDIT: Since I was down-voted for whatever reason, I'd like to rephrase. WSDL is a standardized language for defining web services. It's not a tool in itself for generating client code, and what I said was meant to point out that that's the obvious difference between this and WSDL. A description written in WSDL can both be used to generate client APIs and skeleton code for the server itself, but isn't the generator itself, just like C isn't gcc.
- biot 13y agoYou're being downvoted because this project is a generator program which, as input, takes a specification of the API in JSON format. This JSON specification is what is being compared to WSDL because they serve the same purpose: to define the endpoints, arguments, and return values for a given API.
- 13y ago
- squar1sm 13y agoI think this is fantastic. @sunkarapk, great job. That it's written in Go makes using it so much easier. Wonderful.
- jxf 13y agoJust tried this out and Alpaca is an awesome tool. However, I'd never want to release this in production without tests. Alpaca doesn't generate tests, so you're back to maintaining the tests for your N different platforms/languages. But you'd have the same problem with its competitors, too; Thrift [0], for instance, doesn't generate tests either. Overall, I'm not sure that the time savings is as big as it first appears, but I think it's great for quick projects. [0] http://thrift.apache.org/ http://thrift.apache.org/
- sunkarapk 13y agoTests is one of the main priority and I am planning to do them soon. This current program just a small step in the right direction. :) EDIT: Currently, I have a test suite at https://github.com/pksunkara/alpaca/tree/testing https://github.com/pksunkara/alpaca/tree/testing which tests the generated client libraries of an example API with the respective server.
- X4 13y agoThat sounds cool! Is there a way to automatically generate BDD style Tests? Have a look at http://funkload.nuxeo.org/intro.html http://funkload.nuxeo.org/intro.html
- Robin_Message 13y agoI'm confused by this comment. What would the tests test? My thinking is that, if trusted to output a library that matches the API spec, there is no need to test that API. However, that does require that Alpaca is well-tested enough to be trusted - would you be happy with tests in Alpaca itself, or should it generate tests too?
- jxf 13y agoI guess it depends on whether you view Alpaca as (a) "it's a starting point for generating your API", or (b) "it's the authoritative source and the only way to generate your API". If you use it like (b) you don't need tests, but Alpaca does. If you use it like (a) Alpaca still needs tests, but the buck stops with you.
- acbart 13y agoSo, this is markedly similar to the project I've been working on in grad school, only without static typing. http://research.cs.vt.edu/vtspaces/realtimeweb/ http://research.cs.vt.edu/vtspaces/realtimeweb/ Also, mine is explicitly geared towards education purposes. I'm about one third of the way thru version two, but I wonder if we can cross pollinate our code bases to get something even better.
- bashtian 13y agoI did something similar for Go and Java. It's simpler if you don't need the whole API, but of course not as powerful. https://github.com/bashtian/jsonutils https://github.com/bashtian/jsonutils
- endeavour 13y agoDoes this use the Json Schema spec or have you reinvented the wheel?
- sunkarapk 13y agoJSON Schema is too complex for this project. I just chose the fields which needs to be populated so that I can generate the code.
- sethrin 13y agoNot that I would defend JSON Schema, but yes, you did just reinvent the wheel, and it was also not a new idea. I thought that despite the verbosity of XML, WSDL and associated technologies solved this problem rather better. I have the misfortune to develop in PHP, so pardon the example, but the client-side code went something like this: $PayPal = new SoapClient($WSDLLocation); $PayPal->SomeMethod(); Yes, you can get away with having a less verbose description language if your needs are simpler, but that to me just ends up moving the problem when your needs become less simple. It's not like you can avoid validating your requests in some way, and required/not required is where that starts -- but, I maintain, not sufficient. I most definitely fail to see client code generation as being a necessary step. You could say I've made this mistake myself; the thought process that leads to code like this must not be unique. Web services need documentation if they are to be used, and since that code will only ever talk to other code, it makes sense to have a machine-parseable description. Language agnosticism follows as a matter of course. I'm willing to entertain that XML was a bad idea and JSON Schema is not an improvement, but I still feel that if one must reinvent the concept of a language-agnostic machine-parseable web services description language, one should thoroughly understand the prior art. It may be complex for a reason, and like it or not all that SOAP stuff actually tends to work pretty well. I'm sure I have every reason for wanting to see a better technology suite which is JSON based, and I wish this were it. At the moment I don't think you're headed in quite the right direction.
- gamache 13y agoWouldn't it be wiser to choose a hypermedia format for the API, and then use a generic hypermedia client on whichever platform you like? Then you write just as many client libraries (zero), but the problem of pushing updates to your clients is solved as well. Full disclosure: I wrote such a library for Ruby, called HyperResource. https://github.com/gamache/hyperresource https://github.com/gamache/hyperresource
- sunkarapk 13y agoI agree its nice to do it that way. But I found that not all APIs use hypermedia format. So, I did it this way. :)
- gamache 13y agoAh, that makes more sense. I was under the impression that Alpaca was targeted at people writing the APIs. Neat tool!
- scarmig 13y agoAt risk of writing a vacuous comment but as a supporter of more HN positivity... Damn, HyperResource looks sexy.
- gamache 13y agoI appreciate it -- that was kind of the point. :)
- rhizome31 13y agoI've read most of the book RESTful Web APIs, which advocates Hypermedia as a way to stop having to create client-specific libraries for each and every Web API. But the book doesn't say much about creating such clients. Is there such a generic Hypermedia client for Python? How does this affects performance? Navigating through the maze of a Hypermedia API requires many more requests than just hitting a known endpoint, doesn't it? Do hypermedia clients provide client-side caching? My other concern is that those APIs might be harder to learn than ad hoc fiat standard. The reason why RESTful-ish APIs have been successful is because they don't add any overhead on top of the things they're representing. At first glance, stuff like JSON-LD, Siren, HAL, etc. seem to be bringing back the complexity of things like SOAP that people have fled from.
- mjs 13y agoRegarding bug reports: > Guaranteed reply within a day. That seems difficult to achieve--wonder how they're doing that? (Also, why??)
- sunkarapk 13y agoI am just a single guy. I always make a point to reply back to issues/pull-requests on my open source projects within 24hrs. Yes, sometimes I fail to make it. But it's a rule I want to live by.
- lucaspiller 13y agoGood luck. I found a six month old PR on one of my projects the other day....
- OGC 13y ago"Thanks for your report. I will read it later." Done.
- notastartup 13y agooh man you just killed a major feature of mashape.com
- anonfunction 13y agoClient library generation is something that mashape supports, but currently they generate libraries for: Java, Node, PHP, Python, Objective-C, Ruby, and .NET It looks like alpaca supports: Java, Go, Perl, Clojure, Scala, Obj-C
- memset 13y agoThis is cool. I would suggest that it would be very useful to have this kind of thing for JSON Schema [1], which is what I use with Python code to validate incoming JSON. (I was originally hesitant to using that, but since getting into it, I have yet to run into a use case which it cannot handle.) There is also an RFC for "JSON Hyper Schema" which is intended to describe REST APIs. It doesn't have much library support in much of everything, but I am surprised that it hasn't taken off! I like that this library is fairly opinionated (options for how to authenticate, supported formats, etc.) Though I worry that that creates a bit of inflexibility - for what exactly does "oauth" actually mean, there are always vagaries. Neato! [1] http://json-schema.org/ http://json-schema.org/
- deleted 13y ago[deleted]
- egonschiele 13y agoUseful, well-documented, TODOs right in the readme, and fast response for pull requests. I wish every open source project was like this.
- flippyhead 13y agoI've been enjoying http://apiblueprint.org http://apiblueprint.org
- cvburgess 13y agoThe web page was very pretty, but I still have no idea what this is/does. Help?
- elwell 13y agoGreat idea! Including Obj-C would be very helpful.
- codereflection 13y agoI have to admit, this is very reminiscent of "Add Service Reference" in Visual Studio, a capability to which I have grown to despise over the years. The code was almost always incomprehensible. I cannot tell you how much I loath seeing the comment at the top of a file "This was generated by a tool". Having said that, this tool does look interesting. I hope that a goal is to always make sure that the generated code is as readable, and maintainable, as possible. Also, as mentioned by others, adding generated tests to the generated client libraries is extremely important.
- sunkarapk 13y agoYou can go through the generated code examples at https://github.com/alpaca-api https://github.com/alpaca-api. I tried to make them a lot more readable. :)
- abengoam 13y agoThat looks fantastic, and seems to be in alignment with some things I have been doing lately (generating the server side controller of the API in Clojure + a set of documentation, from a set of definitions of API methods). Good job!
- mmccaff 13y agoWell done! Know what I think would be really neat? If it could be pointed at an instance of Swagger-UI, or use the same discoverUrl that Swagger-UI would use, and spit out the libraries from that. If you're not familiar.. https://github.com/wordnik/swagger-ui https://github.com/wordnik/swagger-ui
- flooby 13y agoWould it be possible to, say, write a definition for the Twilio API in this API description format? That sounds like it would be a wonderful example of its utility.
- kimmel 13y agoI like the SPORE (Specification to a POrtable Rest Environment) approach better. You create a description file in JSON and each native language client can use that file to access the HTTP API. https://github.com/SPORE/specifications https://github.com/SPORE/specifications SPORE already has clients for Clojure, Javascript, Lua, NodeJS, Perl, Python, and Ruby. I have used SPORE in a few projects and I was not disappointed. Another approach to solving the cross language library problem.
- reklaklislaw 13y agofwiw, I experimented along this line, dynamically generating python wrappers from yaml: https://github.com/reklaklislaw/rest_easy https://github.com/reklaklislaw/rest_easy It lacks documentation, a bunch of features, and parts smell pretty bad, but since the topic came up I thought maybe someone would find it interesting, if only vaguely.
- jodoglevy 13y agoVery cool, but why come up with a new API schema rather than use an open standard like OData (http://www.odata.org/ http://www.odata.org/)? Then Alpaca would be compatible with a bunch of APIs that already exist today. In fact, something like this (generating client libraries from APIs) may exist for OData already, but if it does, I've only seen it for .NET and OData (Visual Studio 'Add Service Reference'). This is actually pretty similar to a side project I've been working on called Gargl (Generic API Recorder and Generator Lite) (https://github.com/jodoglevy/gargl https://github.com/jodoglevy/gargl). Haven't gotten around to doing a Show HN post yet, but would love any feedback or to combine efforts. Basically it lets you generate an API for websites that don't have APIs publically available, by looking at how a web page / form submission of that web site interacts with the web server. You record web requests you make while normally browsing a website via a chrome extension, parameterize them as needed, and then output your "API" to a template file. Then this template file can be converted to a client library in a programming language of your choosing.