Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
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)];

In reply to Re: JSON WebService Description with PERl by Rhandom
in thread JSON WebService Description with PERl by several

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others wandering the Monastery: (12)
    As of 2014-11-29 01:33 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      My preferred Perl binaries come from:














      Results (202 votes), past polls