Net:: vs WWW:: vs WebService::
(This blog post will serve as a document that I point to for people to read when I suggest people renaming their third-party-API modules [although not necessarily always from Net:: to WWW:: or WebService::]. I'm currently on a Questhub quest that does exactly this.)
Perl being a glue language, people write many modules to connect to third-party API services. These days, most public API services are web-based. What namespace should you pick for your module?
Net::
A lot of people still use Net:: as a namespace. For example: Net::GitHub, Net::Amazon::Glacier, Net::Backpack.
This namespace is not recommended by PAUSE module naming guideline because it's supposed to be used for modules that implement various network protocols, e.g. Net::DBus, Net::Ping, Net::DNS.
Quoted from said guide: "The Net namespace is one of the most abused namespaces out there. Originally designed as a home for the code that knows how to talk various defined network protocols, such as FTP, HTTP, NNTP, and so on, people started using it for code that merely used the network without knowing anything about it. Modules that interact with websites use the network, but they aren't about the network, and they have much better homes in WWW or WebService. If you are implementing a network protocol rather than an application protocol, then Net might be for you. Otherwise, it isn't."
In short, you probably shouldn't use Net:: for your third-party API module due to its mixed nature. But, as with some people who said that the Net:: namespace is beyond salvation, I no longer suggest that people who currently use Net:: to rename her module to WWW:: or WebService::. And besides, the abovementioned guide is old. People's usage of names evolves over time. Net:: is convenient after all, which is why people keep using it.
WWW::
There are already lots of modules that connect to API services that use this namespace, for example: WWW::Ebay, WWW::Foursquare, WWW::Gittip.
I used to prefer WWW:: because it's shorter than WebService::, but after a recent discussion with Neil Bowers, and seeing the other existing WWW:: modules like:
WWW::Mechanize WWW::Scripter WWW::Robot WWW::Scraper::* WWW::Curl
I'm now slightly leaning to WebService::. The WWW namespace is for general modules related to the World Wide Web, while third-party API module to web service can perhaps use WebService::.
WebService::
Some modules that pick this namespace: WebService::Yelp, WebService::Tumblr, WebService::TVDB.
I recommend you to use this namespace. But take notice of the casing, it's WebService not Webservice (capital letter S). There's currently one module using Webservice and I'm suggesting that it be renamed to WebService.
Conclusion
Use whatever is sensible, and be consistent. Or, draw your own conclusion :-)
A programmer (mostly Perl 5 nowadays).
My CPAN ID: SHARYANTO. I'm sedusedan on perlmonks. My twitter is stevenharyanto (but I don't tweet much). Follow me on github: sharyanto.
I don't particularly like the 'WebService' namespace, it's long, first of all. Net is short for Network, WebService is not.
More importantly, for the end user the fact that the module is communicating over HTTP isn't the most important feature... If Twitter rolled out a ZeroMQ API tomorrow I'd be more than happy to continue to use Net::Twitter without caring what protocol it is now speaking.
Anybody looking for Net::DNS is going to search for 'DNS', just like anyone looking for Net::Twitter is searching for Twitter. Is twitter not being posted to via the network?
I wish it was that simple, or ever simpler...
I suspect people are more likely to search MetaCPAN for Yelp than WebService. So, I see no reason to use WebService, let alone prefer it. I.e. what does it offer? All you've said above is that it exists.
I'd go for WWW::*.
For a moment I wondered about WWW::Service::* or WWW::Business::*, but of course if you're accessing a site via the internet, the WWW is redundant, so even Business::* might fit.
I also quoted that PAUSE guide recommends it, so that's saying something.
Are you saying that we should skip the traditional CPAN way of using namespaces as categories, and go for modules named Yelp instead of WWW::Yelp or WebService::Yelp?
On the other hand, WWW::Service is not a bad idea.
My $0.02; what would be nice is something that connects the module with OSI network protocol map. Net::Protocol::Application::DNS, Net::Protocol::Transport::TCP and even Net::Protocol::Application::HTTP::Github::API::JSON vs Net::Protocol::Application::HTTP::Github::API::XML or Net::Protocol::Transport::ZeroMQ::Twitter to use the example above.
But it looks like authors chose to go the Net::RRD::Protocol and Net::BGP::Transport route, and other variations, instead of Net::Protocol::Application::RRD and Net::Protocol::Transport::BGP naming which would A) Make sense and B) Be guessable when looking for something.
Not a bad suggestion also! Though I'd abbreviate them a bit. Not just for the fingers, but for the eyes. For example: Net::Proto::App::HTTP, Net::Proto::Transport::ZeroMQ. Although having Net::Proto prefix alone (Net::Proto::HTTP, Net::Proto::ZeroMQ) is a huge improvement already.
WWW implies it's using an unofficial api by scraping the html pages. WebService implies it's using an official api, whatever the transport method. There's also a lot of authors who create top-level namespaces like $site::Client or $site::API. And then there's the authors who go overboard and bloat their module names with redundant components, like: Net::$site::API, WWW::$site::API, WebService::$site::API, Net::$site::Client - all of which are not uncommon.
PAUSE guidelines are important, but it's still up to each author to think about the structure of the name they choose.
My question remains: What does 'WebService' add to the mix?
What about something like Docker? It has a REST API, but it isn't like a proper web service, but it also isn't a network protocol. There is currently Net::Docker.
Is it not possible to restrict people from adding more modules to the Net namespace without review and approval?
That's not how PAUSE or the Perl community works. Unless there's spam or some technical glitch, people are free to submit new CPAN modules in any namespace.