5 ms·

Introducing Geekier, an open source & saner approach to working with APIs

41 points by kevindykes 14y ago

paulnelligan 14y ago
I can personally vouch for Kevin and his team's work here in Berlin. It has already improved my quality of life!
- kevindykes 14y ago
  Paul, thanks for your comments and support! We're excited to get the Berlin community involved as well.
algorithmmonkey 14y ago
This is really starting to sound like what java / .net were doing with wsdl code generators via soap. 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 http://stateless.co/hal_specification.html) be a start down a path where we can have lightweight services that are also self documenting?
- cweis 14y ago
  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.
  - eternalban 14y ago
    GET http://wombat.com/resources/foo/apidoc http://wombat.com/resources/foo/apidoc ==> A "RESTful" resource ... http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
  - algorithmmonkey 14y ago
    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.
    - alpinegizmo 14y ago
      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.
- caseysoftware 14y ago
  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.
  - alpinegizmo 14y ago
    I suggest you look at the work on "interface driven development" with swagger: https://groups.google.com/forum/#!msg/swagger-swaggersocket/cB0uApmcVjE/w_r40tnzmykJ 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.
JPKab 14y ago
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.
- cweis 14y ago
  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.
- alpinegizmo 14y ago
  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.
espadagroup 14y ago
Looks like the dev version of Zapier.com
- kevindykes 14y ago
  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.
peregrine 14y ago
Sounds a lot like the hypermedia discussions going around....
- alpinegizmo 14y ago
  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.
- cweis 14y ago
  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.

41 points by kevindykes 14y ago

paulnelligan 14y ago

I can personally vouch for Kevin and his team's work here in Berlin. It has already improved my quality of life!

kevindykes 14y ago
Paul, thanks for your comments and support! We're excited to get the Berlin community involved as well.

algorithmmonkey 14y ago

This is really starting to sound like what java / .net were doing with wsdl code generators via soap. 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 http://stateless.co/hal_specification.html) be a start down a path where we can have lightweight services that are also self documenting?

cweis 14y ago
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.
- eternalban 14y ago
  GET http://wombat.com/resources/foo/apidoc http://wombat.com/resources/foo/apidoc ==> A "RESTful" resource ... http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- algorithmmonkey 14y ago
  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.
  - alpinegizmo 14y ago
    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.
caseysoftware 14y ago
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.
- alpinegizmo 14y ago
  I suggest you look at the work on "interface driven development" with swagger: https://groups.google.com/forum/#!msg/swagger-swaggersocket/cB0uApmcVjE/w_r40tnzmykJ 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.

JPKab 14y ago

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.

cweis 14y ago
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.
alpinegizmo 14y ago
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.

espadagroup 14y ago

Looks like the dev version of Zapier.com

kevindykes 14y ago
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.

peregrine 14y ago

Sounds a lot like the hypermedia discussions going around....

alpinegizmo 14y ago
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.
cweis 14y ago
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.