

Introducing Geekier, an open source & saner approach to working with APIs - kevindykes
https://github.com/rulesio/geekier/wiki

======
algorithmmonkey
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>) be a
start down a path where we can have lightweight services that are also self
documenting?

~~~
cweis
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.

~~~
algorithmmonkey
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
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.

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

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

------
JPKab
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.

~~~
alpinegizmo
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.

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

~~~
cweis
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.

------
espadagroup
Looks like the dev version of Zapier.com

~~~
kevindykes
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.

