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.


Posted

in

by

Tags:

Comments

22 responses to “Perl APIs”

  1. Caleb Cushing Avatar

    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. Drew Taylor Avatar

      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. Caleb Cushing Avatar

    Also MooseX::RemoteHelper was written to make it easy to write a Perl Wrapper around a remote API, I welcome contributions.

  3. neilbowers Avatar
    neilbowers

    Yes, I think this is very much a worthwhile project!

  4. joe Avatar
    joe

    Also look at projects like https://github.com/wordnik/swagger-codegen (no perl support) or https://github.com/pksunkara/alpaca (perl is ‘TODO’)

    1. wing328 Avatar
      wing328

      Perl support (beta) has been added to swagger-codegen (https://github.com/wordnik/swagger-codegen). Please give it a try as follows:

      git clone https://github.com/swagger-api/swagger-codegen.git
      git checkout develop_2.0
      mvn clean && ./bin/perl-petstore.sh

  5. Gerald Avatar
    Gerald

    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.

  6. Gerald Avatar
    Gerald

    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.

  7. Paul S Avatar

    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.

  8. David Precious Avatar

    Certainly a worthwhile way to promote Perl.

    You’ve inspired me to remind the author of the API I use to snap thumbnail images of web pages, http://webthumb.bluga.net/ of the existence of the wrapper I wrote to use it, https://metacpan.org/pod/WebService::Bluga::Webthumb

    Incidentally I think you meant s/Approve/Approach/ in #3, no?

  9. Caleb Cushing Avatar

    @Paul S the whole point of Moo is that it’s lighter because it doesn’t have a MOP. (Note: MooseX::RemoteHelper uses Moose because it makes heavy MOP usage)

  10. Theo van Hoesel Avatar
    Theo van Hoesel

    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

  11. Mark Gardner Avatar
    Mark Gardner

    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.

  12. Paul S Avatar

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

  13. ambrose chapel Avatar

    By “Approve API owners” you mean “Approach API owners”, I believe?

  14. Gerald Avatar
    Gerald

    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?

  15. Paul S Avatar

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

    1. nigehamilton Avatar

      Great idea. I too have lamented the lack of Perl mentions in REST API descriptions.

      Checkout http://enunciate.codehaus.org/ it apparently automatically generates client code in various languages – perl is not one of the generated clients 🙁

      Could this be one for the perl-api-squad?

  16. Lao Dee Avatar

    I have an almost complete Magento interface, based on Moo, and XML::RPC::Fast, and Log4Perl. works brilliant for quite intense project.

  17. […] perl hacks: Perl APIs […]

  18. ggl Avatar
    ggl

    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.

  19. Mohammad S Anwar Avatar

    Cool idea, I have published on CPAN some for Google API.

    http://search.cpan.org/~manwar/

    I would love to be a part of this project.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.