Perl APIs

For a lot of programmers out there, Perl has become largely invisible. They just never come across it. That might seem strange to you as you sit inside the Perl community echo chamber reading the Perl Ironman or p5p, but try this simple experiment.

Think of a web site that you use and that supplies an API. Now go to that API’s documentation and look at the example code. What languages are the examples written in? PHP? Almost certainly. Ruby? Probably. Python? Probably. C#? Quite possibly. Perl? Almost certainly not[1].

Perl has fallen so far off the radar of most people that when web sites write example code for these APIs, they very rarely consider Perl as a language worth including. And because they don’t bother including Perl then any random programmer coming to that API will assume that the API doesn’t support Perl, or (at the very least) that the lack of examples will make using Perl harder than it would be with plenty of examples to copy from.

This then becomes a self-fulfilling prophecy as Github fills with more and more projects using other languages to talk to these APIs. And the chance of anyone who isn’t already a Perl user ever trying to interact with these APIs using Perl falls and falls.

Of course, this is all completely wrong. These APIs are just going to be a series of HTTP requests using REST or XML-RPC (or, if you’re really unlucky, SOAP). Perl has good support for all of that. You might need to use something like OAuth to get access to the API – well Perl does that too.

Of course, in some cases good Perl support exists already – Net::Twitter is a good example. And to be fair to Twitter, their API documentation doesn’t seem to give any examples in specific languages – so Perl isn’t excluded here. But in many other cases, the Perl version languishes unnoticed on CPAN while other languages get mentioned on the API page.

I think that we can try to address this in 2014. And I’d like to ask you to help me. I’ve set up a mailing list called perl-api-squad where we can discuss this. In a nutshell, I think that the plan should be something like this:

  1. Identify useful APIs where there is either no Perl API or no Perl examples
  2. Write CPAN API wrappers where they are missing
  3. Approve API owners and offer them Perl examples to add to their web site

That doesn’t sound too complicated to me. And I think (or, perhaps, hope) that most API owners will be grateful to add more examples of API usage to their site – particularly if it involves next to no effort on their part.

I also expect that the Perl API Squad will produce a web site that lists Perl API support. We might even move towards producing a framework that makes it easy to write a basic Perl wrapper around any new API.

What do you think? Is this a worthwhile project? Who’s interested in joining in?

[1] Yes, I know there are exceptions. But they are just that – exceptions.

21 thoughts on “Perl APIs

  1. RE: SOAP being worse than XML-RPC, having worked with a properly written WSDL/XSD SOAP API (Cybersource SO API, and PaperlessTransaction Backend ), and a not so well written one Magento, which I ended up using XML-RPC for, and a XML API which used a bastardized SOAP with embedded XML docs ( ASP.net StoreFront ) a properly written SOAP API is way nicer to use in Perl than XML-RPC, because XML::Compile::SOAP is awesome. Unfortunately most “SOAP” API’s aren’t validly SOAP. XML::RPC has unicode problems, and XML::Compile::RPC returns nasty data structures.

    1. I used XML::Compile and friends to interface with a massive SOAP backend a few years ago. Without it, using perl simply wouldn’t have been an option. At the time I left that job I *still* didn’t have my head fully around everything XML::Compile could do, but the code did work quite nicely if I do say so myself.

  2. I applaud your efforts but it doesn’t address the root problem which is why these API authors don’t provide Perl APIs in the first place and that, I’m afraid, is down to dwindling Perl mindshare. How many Perl books are published each year these days? When a Perl book eventually appears it tends to be yet another general Perl guide rather than anything applied. Perl needs some Pragmatic Programmer titles to start looking relevant again. I was more or less forced to switch to Ruby this year to keep my skills relevant.

  3. Perl also lacks a sense of urgency. It fails to compete in the web development domain with Ruby and PHP yet the community is still vacillating about adding p5 MOP to the core and getting Perl 6 out the door. Perl will continue to hemorrhage mindshare so long as its OO support flounders like this. A modern language should not require a separate module like Moose (and variants) to inject decent OO. The lack of baked-in OO could easily be the reason why some API authors have left Perl out in the cold.

  4. New APIs that use the full Moose rather than a more trim Moo currently aren’t an option on our systems. The politics of such a decision aren’t as relevant, but I know that this same policy exists at many perl based shops. If you must mop, please use Moo.

  5. Currently I am working on Magento::Backend. the API of Magento is horrible, they have XML-RPC (the most solid), SOAP (with invalid WSDL) and REST (which is sooo incomplete). Magento::Backend is a full Moose wrapper around their calls. I saw no other solution for the project I am working on, the code would become unmaintainable.

    Now instead of dozens of lines of silly code, I manage the Magento Webshop remotely with just a few lines of code.

    But it would be great indeed that there would be proper Perl examples with all those APIs

  6. I’m working on an internal project that uses the NetSuite API via XML::Compile::WSDL11 and have kept the proprietary bits separate with an eye towards releasing the generic NetSuite bits as a CPAN distribution. Definitely interested in participating in this larger project, so I’m subscribing to the mailing list.

  7. @Caleb – I hadn’t seen that Moo pod claimed to be “no metaprotocol,” but checking CPAN it lays that claim. I personally have always thought that external helpers for class/role/attribute composition are very meta, even if there are not also introspection and runtime method creation features, and function wrappers, and all of the other Moose goodness.

  8. If Perl had decent OO baked in it might have been included in an API such as this one: http://vertx.io/docs.html which offers a concurrent web layer to single-threaded OO languages. How can Vert.x offer a Perl API with our TIMTOWTDI “use /Mo\w+/;” approach to OO?

  9. @Gerald – This really seems like the wrong forum, or maybe it isn’t, but Perl’s TIMTOWTDI-ness and particularly its lack of a standardized object system does not feel like the reason that others aren’t implementing APIs in perl. Normally I see bindings for C++/Java. If your lucky there will be Python. If they are progressive there will be JavaScript/Node. If you are really really lucky there will be Ruby. Perl isn’t currently a “cool-kid-on-the-block” so nobody automatically writes bindings.

    Realistically – most of the world is now just writing rest and leaving the foreign languages deal with it themselves.

    Dave’s proposal is a good one in that we can turn around and offer the bindings back to the locations – at which point Perl is listed as a binding, and possibly creating the illusion that Perl is once again a must-have or a cool-kid-on-the-block for other people creating new bindings.

    So I don’t really see the Moo/Moose/Hash-based-oo as being the issue of missing perl API bindings. The Moose issue determines if I can use the API on my perl platform. I can’t use the Moose based modules Caleb and others are writing – but others could and they would qualify as perl bindings none-the-less and could be listed next to the other languages.

  10. If your API binding depends on Moose, I refuse to use it. Why? Because it forces an unnecessary long dependency chain upon my code. I would (rather reluctantly) use it if it depends on Moo, though.

Leave a Reply