http://www.perlmonks.org?node_id=969466


in reply to JSON WebService Description with PERl

I've dealt with WSDL and other representations. Coming from a mostly perl world, I really don't care for anything that I've seen. I just read the JSON-WSP service description you listed. It is a little better than WSDL, but only just a little. Most of the service description protocols seem to want to be able to wrap any function taking any type of arguments and returning any type of data. You can see this with various warts such as the doc_lines and def_order constructs of the JSON-WSP description. Those aren't really important details for what the method does - but represents an almost too literal representation of the underlying python library. I can see right off that it would make reordering the subroutine at a later date very problematic.

I've built well over a dozen protocols for various services. Over the years they have all migrated towards JSON over HTTP. I've gotten to the point where I don't really care about being able to wrap any subroutine signature under the sun. I've given myself a very simple layout.

  1. I require a method name - I typically like to pass this along in the path info so that my access logs are more meaningful.
  2. My arguments coming in are always a hashref.
  3. My response is always a hashref.
  4. If there is an error situation, there will be a key in the response called "error."
That is it. Those are all the rules. Exposing methods is always easy. Writing AJAX request/response handlers is always easy. Writing clients is always easy.

Since I have an easy format to follow, my meta description service is easy to write to as well. If I exposed a method called "foo," I would also write an accompanying sub called "foo_meta" which returns a very simple descriptive data structure. Here is one that I wrote within the past month or two:

sub __profile_meta { return { desc => 'Return an existing domain site profile', args => { domain => { desc => 'Domain for which to fetch the profile', required => 1, type => 'domain', }, file => { desc => 'Optional - The file location' .' where this profile is installed.' .' Defaults to profile.html", required => 0, }, }, result => { file => 'The file that this profile' .' will be installed at", body_logo => "Logo for the page", body_sections => [{ type => 'Type of content', html => 'The content itself', }], body_slogan => "Slogan for the page", contacts => [{ name => "Name for this contact", email => "Email for the contact", }], meta_description => 'Meta tag description', meta_keywords => ['List of keywords'], }, }; }

I've found that I can fit pretty much anything I need to into this scheme. Of course YMMV.

my @a=qw(random brilliant braindead); print $a[rand(@a)];

Replies are listed 'Best First'.
Re^2: JSON WebService Description with PERl
by several (Acolyte) on May 08, 2012 at 14:09 UTC

    Thanks for your opinion on this - I'm a fan of rather simple things that over-enginered ones! The fact that there is no standard or default way to do this implies that the work needed to define, implement one is higher than just documenting and doing it the fast way - which is just fine!

    Thanks for the profile example - looks good, but probably lots of implementation needed when it comes to binding Java Services to it :)

      "but probably lots of implementation needed when it comes to binding Java Services to it

      Possibly true.

      My consumers have typically been perl, javascript, php, or python - all dynamic folk. Yes - potentially there could be a little more work for those using Java, but I don't really think there would be that much more. In actuality I doubt any existing JSON service would be much easier to bind to Java. Unless you are using a WSDL I doubt there are many (if any) JSON web service libraries that would do the automatic type conversions that you get with WSDL.

      Either way, Java will likely have top-notch JSON classes - and if they do then constructing an appropriate JSON message would not be difficult, nor would getting information out of a JSON response and type casting. Ultimately that isn't really that more work than fiddling with WDSLs and having to pull information out of the automatically parsed structure returned by the SOAP libraries. The real time it is faster and easier with SOAP is when you are passing struct type objects and consuming those objects on the client end - very little of my work has ever wanted to deal with information in that form.

      my @a=qw(random brilliant braindead); print $a[rand(@a)];