Introducing Geekier, an open source & saner approach to working with APIs(github.com)
github.com
Introducing Geekier, an open source & saner approach to working with APIs
https://github.com/rulesio/geekier/wiki
5 comments
I think separating the documentation step (machine-readable or not) from the actual development process is what makes the entire process painful. It means you have to have parallel development or things get out of sync pretty easily.
I've sketched out some work on using OPTIONS and having the code introspect itself to describe how to interact with the API. Basically with good validation, error messages, and solid/consistent naming conventions, you can take it a long way before you have to step out of the development that you're already doing.
I've sketched out some work on using OPTIONS and having the code introspect itself to describe how to interact with the API. Basically with good validation, error messages, and solid/consistent naming conventions, you can take it a long way before you have to step out of the development that you're already doing.
I suggest you look at the work on "interface driven development" with swagger: https://groups.google.com/forum/#!msg/swagger-swaggersocket/...
There's plenty that API providers can do to make things saner for all of us, and themselves. Problem is, many (if not most) of them don't seem to care enough. As users of APIs we are their customers, and we outnumber them. Let's find a way to show them the benefits of making our lives easier.
There's plenty that API providers can do to make things saner for all of us, and themselves. Problem is, many (if not most) of them don't seem to care enough. As users of APIs we are their customers, and we outnumber them. Let's find a way to show them the benefits of making our lives easier.
This is a good point that we discussed, too. While Hal, like HATEOAS is very interesting and definitely a simplification that's necessary to make our lives better, we're aiming at something different: we're trying to describe existing (ReST) APIs in a way that a single library using a Factory Pattern can turn into connections that you as a developer can use to work with that API.
We settled for the swagger format, because its very flexible, human-readable and honestly can be turned into very nice looking documentation pages.
I'm not knocking what you are doing. I love the effort, and I think it will improve developer experience for the most part. I'm just raising the questions of "Should we have to do this?" and "Didn't we go down this path before?".
The thing that the library is doing, is now replacing a wsdl with an expert that develops a swagger document. This to me sounds problematic. The wsdl had some idea of versioning of the contract, and was dependent on the developer of the service to update the wsdl with updates of their service.
I imagine, and correct me if I'm wrong, but the swagger doc will have to updated by the expert per release of the service (obviously, pending any implementation changes of the service). This actually puts the consumers of the framework at risk of incompatibility via 1., the developer changing the service, and 2., the expert not updating the swagger definition upon 1. Is this accurate?
Please don't take this as me saying that I'd like to go back to wsdls. That is certainly not at all what I'm advocating.
The thing that the library is doing, is now replacing a wsdl with an expert that develops a swagger document. This to me sounds problematic. The wsdl had some idea of versioning of the contract, and was dependent on the developer of the service to update the wsdl with updates of their service.
I imagine, and correct me if I'm wrong, but the swagger doc will have to updated by the expert per release of the service (obviously, pending any implementation changes of the service). This actually puts the consumers of the framework at risk of incompatibility via 1., the developer changing the service, and 2., the expert not updating the swagger definition upon 1. Is this accurate?
Please don't take this as me saying that I'd like to go back to wsdls. That is certainly not at all what I'm advocating.
We do intend to version the swagger docs, so that a specific description will point to a matching version of the service. A new version of the doc will have to be created whenever the service is updated. Our goal is to get a large developer community involved, at which point the API owners will find it worthwhile to do this themselves.
GET http://wombat.com/resources/foo/apidoc ==> A "RESTful" resource ...
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
I can personally vouch for Kevin and his team's work here in Berlin. It has already improved my quality of life!
Paul, thanks for your comments and support! We're excited to get the Berlin community involved as well.
algorithmmonkey hit the nail on the head: this sounds a HELL of a lot like WSDL and the WS* method in general. I HATE the WS*. However, I'm not going to knock what they are doing, because it is certainly a noble effort. Could someone who is much smarter than me explain how this would avoid the pitfalls of past attempts at abstracting service layers?
It's interesting to see the approach of abstractable APIs, vs. the other way of making usage of data more automatic, via machine readable semantic markup and embedding metadata into the data structure aka linked data/semantic web.
I think its all awesome.
It's interesting to see the approach of abstractable APIs, vs. the other way of making usage of data more automatic, via machine readable semantic markup and embedding metadata into the data structure aka linked data/semantic web.
I think its all awesome.
With Geekier our primary goal is to make things better for folks, like us, who are building apps using the APIs available today. We've come up with a pragmatic solution that lets us decouple our applications from the APIs we're using. It's pretty simple and doesn't try to solve every conceivable case, which is hopefully how we'll avoid the pitfalls of some past attempts at this.
We're not so much trying to make this an abstraction layer as we want to make this a library of API definitions that are clear, machine- as well as human-readable (to a point) format, that can be made usable by a connection factory instead of making it necessary to generate and maintain libraries.
I hope that addresses some of your questions.
I hope that addresses some of your questions.
Sounds a lot like the hypermedia discussions going around....
This is a very interesting discussion to me. I'm still on the fence about the idea of putting links in API formats. For HTML that works of course, because we understand contexts and meanings. Usually. But libraries have a harder time doing this and semantics only goes so far.
Another short term problem I would see is adoption of this on the API provider side. That's of course something a well coordinated initiative would take care of.
I'm looking forward to seeing where this goes and learning more about it.
Another short term problem I would see is adoption of this on the API provider side. That's of course something a well coordinated initiative would take care of.
I'm looking forward to seeing where this goes and learning more about it.
I haven't been following those discussions very closely, so I'd love to hear more. It's not clear to me where that hypermedia approach might take us, as a community. My first impression is that this feels like an approach that requires more upfront buy-in from the API providers, and puts a fair bit of burden on all the clients.
Looks like the dev version of Zapier.com
We really think Zapier has done an amazing job in building a gorgeous UI, easy to understand UX and gaining support from the API community. But, obviously they are really well suited for end users and not as much so (in our opinion) for devs needing to talk to a bunch of API's directly. As the need to talk to many API's was at the core of rules.io, it made sense to us to try to gain support from the community for some standards and to contribute descriptions.
Our goal is to really better support the needs of app developers needing to work with many API's rather than the API developer themselves. But we hope to gain support of both.
Our goal is to really better support the needs of app developers needing to work with many API's rather than the API developer themselves. But we hope to gain support of both.
Devs that integrate with multiple apis know there is a problem with the wide range of implementations, from authentication to communication patterns. This makes it a pain to integration with multiple service providers. Without some form a standardization you must have an intermediary library to provide an abstraction.
Are we doing it right?? The community has recognized the problem of non-standard lightweight services to be widespread enough to create a tool to standardize communication with them.
Would something like HAL (http://stateless.co/hal_specification.html) be a start down a path where we can have lightweight services that are also self documenting?