Plans for the immediate future

[Chris Weis]

Geekier (https://github.com/rulesio/geekier/wiki) will be a set of tools that we plan to open source bit by bit and we'll start with the innermost (https://raw.github.com/rulesio/geekier/master/images/geekier-and-em.png) part of it - the factory and a repository of API descriptions to work with.

The first two pieces:

API description repository

For now, we're going with Swagger as the description format, but the jury is still out on what we'll end up using. There's another thread here (https://groups.google.com/d/topic/geekier-apis/TfSU_tcNPgA/discussion) where we're discussing formats and requirements.
The format itself doesn't make too much of a difference for the repository though - the main work here goes into structuring it in a way that makes sense and that'll be done soon.

API connection factory

There will be a first release of this before the end of the year, but that'll still be subject to a lot of changes as it evolves. Especially because it will use the Swagger format, even though, that decision is not final. So as soon as this piece is out (and we'll let you know here, too), please feel free to weigh in with opinions and contributions so we can make this as good as it can be.

Please bear with me a bit longer and I will happily get this into your hands!

--
Chris Weis

rules.io, Berlin

[Dan Applegate]

I'm a PHP developer, and last year during a project, I found myself having to work with a relatively new API that did not have the support of a native PHP library. I'd always been disappointed with the implementations of a lot of other popular PHP libraries for integrating with various HTTP APIs, so I ended up writing my own. In a lot of ways, it emulated Geekier's basic structure.

I had an XML file where I defined the endpoints of the API and the parameters it could accept (along with default values), and a generic interface library which mapped arbitrary method calls to their underlying XML schema definitions. Then, my library code was relatively slim and straightforward, and to add new endpoints as they were released by the API providers, I simply had to modify the XML file. It sped up development considerably, which led to my interest in adapting this type of solution to multiple APIs and languages.

I say all of this to propose: Is there any interest in simultaneous development of a PHP port of Geekier? The beauty of it would be that any decisions made about the underlying format would benefit both projects, as would decisions about the structure of the Geekier library itself.

Any thoughts?

Dan

[alpin...@gmail.com]

| Is there any interest in simultaneous development of a PHP port of Geekier?

Absolutely! I think that sounds great.

I'm currently preparing a couple of initial description files that we can use as a starting point. Are there any APIs that you are particularly interested in? 

To simplify testing, I'm looking for APIs that don't require any authentication, and that produce repeatable results. So far I've done some work on sendgrid, but sendgrid requires an api_key. I want to write some end-to-end tests that actually exercise an API and test that the results are correct -- and I want to share those tests and have everyone be able to run them. For that, an API that doesn't need authentication will make things easier as we get started. One idea would be to use parts of the github API that can be called anonymously. Other ideas?

I also plan to start building a suite of test cases that can be shared across different ports of Geekier. A test case would be something like "call this operation on that API with these parameters, and the response should look like this". The test cases can be in JSON or YAML, we can write a simple test runner for each port of Geekier.

--David Anderson

  rules.io

[Aidan Feldman]

You could try the Facebook Graph API for a Place or something else fairly static.

It might make sense to save the responses from APIs for faster/more reliable test running (via VCR, or the equivalent), but set up a test server that has API keys to make actual requests periodically to make sure the descriptions are still consistent with the results coming back.

--
You received this message because you are subscribed to the Google Groups "Geekier APIs" group.
To unsubscribe from this group, send email to geekier-apis...@googlegroups.com.
Visit this group at http://groups.google.com/group/geekier-apis?hl=en.
 
 

[Chris Weis]

Hello Group and belated greetings of the season!

I'm very sorry, I haven't posted anything lately, but I've been sick during the holidays and wasn't able to do much in terms of coding.

That's also why this:

Am Mittwoch, 19. Dezember 2012 16:39:21 UTC+1 schrieb Chris Weis:

API connection factory

There will be a first release of this before the end of the year, but that'll still be subject to a lot of changes as it evolves.

turns out to take a bit longer than I initially hoped. I'm back the the keyboard now and trying to get the Factory working and into the repo as quickly as possible.

Thanks a lot for your patience

[Dan Applegate]

I also plan to start building a suite of test cases that can be shared across different ports of Geekier.

Hi David, I've been thinking about your suggestion of using a unified suite of test cases across different ports of Geekier. I really like the idea, as it would introduce a lot of uniformity and QA automation across the different ports.

Through some light research of BDD, I came across Gherkin, a language for defining the features required of a piece of software. Although initially developed to support BDD in ruby through Cucumber, there are also libraries in PHP and Python which understand it.

I was wondering if you had any experience with Gherkin? It seems targeted towards providing a communication medium between business people and coders, but it might prove useful to us by keeping our launguage-specific test suites in compliance with the necessary features of Geekier. I imagine that our feature definition files could be contained in a separate repository that we would then submodule into our respective code bases. From there, we would use Cucumber, RSpec or Behat to evaluate whether or not our test suites cover all the required features.

What do you think?

Dan

[Aidan Feldman]

I've used Cucumber/Gherkin in the past: I personally think it's better suited to interactions and workflows than unit-y tests like this, but it is nice that it's language-agnostic.

How do people imagine automated tests would work?  You do want to test the live API to make sure it's still compatible, but you then can't ensure the state of the user or whatever resource you're testing against, especially since multiple people could be running the test at one time.  Mocking the web requests is probably the only way to go.

--

[Dan Applegate]

You do want to test the live API to make sure it's still compatible

The way I see it, the specification files are more like data rather than part of the code base, the idea being that eventually any third-party could write a specification file and have Geekier interact with that API. It seems to me, then, that we can only ensure compatibility between the API specification file and our own code. If those are compatible, then the incompatibility is really between the specification file and the service itself, which would prove a constant nightmare to keep covered by automated tests.

Put another way, if we include the specification files as part of our tested code base, that would mean that we would need to update our test suite and code with each change to every API that Geekier supports.

So in my mind, our test suites should only cover accurate parsing of specification files, generation of API interfaces, and translation of API calls into proper web requests. Beyond that, if something breaks, then it's because of bad data.

Although, the guys at rules.io might already have something entirely different in mind.

Dan

[David Anderson]

I think what I'm hearing here matches my perspective, which is that there are two separate concerns which we should address independently. I'm planning to create one set of tests that assumes that a specification correctly describes an API, and then validates that our code uses that specification to correctly call the API, etc. This first set of tests won't need to touch the actual API. The second set of tests would serve the purpose of testing that the descriptions accurately describe the actual behavior of the live API. 

I think this second set of live API tests adds a lot of value -- in the beginning helping to ensure that we have created accurate descriptions, and down the road, detecting when APIs change their behavior. There are some logistical issues involved -- but we don't all have to run tests against the live API all the time. As a community we can figure out somewhere for that to happen, and share the results publicly.

--david

[Dan Applegate]

Hi David, yes, I think you've summed it up nicely. As you describe it, it seems that it might be useful to think of the functionality for testing the compliance of an API as a feature of the library, rather than merely a set of internal tests we run. This feature could then be used in a variety of ways to the end user, such as automatically detecting changes in the API as you suggest, or a "validation" server which would allow users to upload schema files and validate them against APIs.

As for the use of Gherkin as a common test language, yes, it is typically more often used for user experience and workflows. However, at its core it is simply a library for matching natural language sentences in a feature file to annotated tests, and so could be adapted for our use.

Dan

[Chris Weis]

We've finally made it!

You can find the ruby version here: https://github.com/rulesio/geekier_factory_gem.

Please check it out and let me know of any questions or comments you have.
And feel free to fork and modify it, reimplement it in other languages or start flamewars about it :)