[prev in list] [next in list] [prev in thread] [next in thread] 

List:       bricolage-devel
Subject:    Re: RFC: SOAP interface
From:       "David E. Wheeler" <david () kineticode ! com>
Date:       2008-01-22 21:41:52
Message-ID: 717CD8DD-1198-4CC1-8F60-0F61BD5F6294 () kineticode ! com
[Download RAW message or body]

On May 15, 2007, at 08:42, Scott Lanning wrote:

> This is a Request For Comments on the SOAP interface.
> It's not a Promise To Implement Anything, though. :)
>
> This is kind of in notes form, so sorry if some of it
> doesn't make sense; just things I jotted down as I kind
> of reverse-engineered the way bric_soap works.
> (obviously related to the WSDL post I just sent to users@ .]
>
>
> SIMPLIFICATION
>
> list_ids request
>
> The <soap:Body> of a list_ids request looks like
>
> <list_ids xmlns="http://bricolage.sourceforge.net/Bric/SOAP/Story">
> <element_key_name xsi:type="xsd:string">story</element_key_name>
> <primary_uri xsi:type="xsd:string">/%</primary_uri>
> etc...
> </list_ids>
>
> where the stuff inside <list_ids> is one element for every time
> you put --search something="..." on the command-line of bric_soap.
> Tying this to SOAP/WSDL -- i.e. describing an API --  list_ids is
> a method name whose named parameters are element_key_name,  
> primary_uri, etc..
> This is clearly crazy once we realize that there are dozens
> of possible parameters, some of which can be given more than once;
> for example, the story->list_ids method has 67 parameters!
> (if we include a few duplicates) This works fine in Perl,
> but I imagine it doesn't for some other languages (ideally the SOAP
> interface would be language-neutral).
>    I'm not sure what the best way to do it would be, but maybe we
> could at least wrap the search parameters in a <search> element
> or something. The idea is that there'd now be only one parameter,
> so frameworks that generate methods could possibly do that.
> I'm not sure if they'd handle that or not, though.

I'm not sure I follow. What is it your proposing, exactly? Can you  
give an example?

> list_ids response
>
> The list_idsResponse message doesn't have to include the module name.
> For example, the <soap:Body> of a category search looks like:
>
> <list_idsResponse
> xmlns="http://bricolage.sourceforge.net/Bric/SOAP/Category">
> <category_ids soapenc:arrayType="xsd:int[1]"
>               xsi:type="soapenc:Array">
>  <category_id xsi:type="xsd:int">1</category_id>
> </category_ids>
> </list_idsResponse>
>
> It could be more generic:
>
> <list_idsResponse
> xmlns="http://bricolage.sourceforge.net/Bric/SOAP/Category">
> <ids soapenc:arrayType="xsd:int[1]"
>      xsi:type="soapenc:Array">
>  <id xsi:type="xsd:int">1</id>
> </ids>
> </list_idsResponse>
>
> This would simplify the WSDL by allowing the same schema type
> to be used for all the modules. It would also incidentally save
> a few bytes per "asset" listed (imagine you have a lot of categories
> or stories or media, for example), though obviously there are much
> more compact ways to do that if that was what we were interested in.

And can you tell that it's category IDs and not story IDs because of  
the xmlns attribute?

> export request
>
> Same argument as for "list_ids response". We can use "ids" instead
> of more specific parameters like "media_ids". However, there are
> some exceptions, now that I think about it.

Like what?

> Furthermore, I don't think we need both foo_id and foo_ids,
> just foo_ids will also work for one ID.

Agreed.

> create response
>
> Interesting that this uses <ids> instead of more specific like
> <category_ids>... But it still uses <category_id> inside that,
> which would better be <id>, as above.

Sure.

> Is Base64-encoding in fact the best way to send the data?
> Why not just the XML that you pass to bric_soap (XML-encoded)?

Dunno. It could have binary data, no? Especially templates.

> update request
>
> When sending a create request, you just send a <document> element
> which contains Base64-encoded XML. For an update request, you also
> send an array of <update_ids>. I don't see why that's necessary.
> Each ID could (I assume) be gotten when the document is decoded.

Sure.

> Also, as above, the elements inside <update_ids> could be <id>
> instead of more specific names.

> update response
>
> See create response, which is identical

I've often wondered if we could support some sort of diff format for  
updates, so that we don't have to send the whole document. It always  
seemed silly to me to send the whole thing if all you wanted to do  
was, for example, change the category of a story.

> delete request
>
> Same as export, I don't think we need both foo_id and foo_ids
> parameters, just foo_ids will also work for one ID.
> And <ids> instead of <foo_ids>.

Right.

> publish request and response
>
> This is an exception to where we could use <id> instead of <media_id>
> or <story_id>, because workflow publish <publish_ids> can contain  
> both.
> <publish_ids> could be called <ids>, though.

Or

<story>
  <ids>
    <id>...</id>
  </ids>
</story>

No?
> deploy, checkin, checkout request and response
> <deploy_ids>, <checkin_ids>, <checkout_ids> could be <ids> instead.

Lots of ID-related changes. Low hanging fruit?

> NEW FUNCTIONALITY
>
> I think there should be a lot more little commands.
> For example, how do you find out what desk/workflow
> a story is on? It'd be nice to be able to do
>
>  $ bric_soap story location story_1024
>
> and have it return, say,
>
>  <location>
>   <site>Default Site</site>
>   <workflow>Story</workflow>
>   <desk>Edit</desk>
>  </location>
>
> or just
>
>  $ bric_soap story workflow story_1024
>
>  <workflow>Story</workflow>
>
> Anyone who's used bric_soap has probably wanted this kind of thing:
>
>  $ bric_soap story primary_uri story_1024
>
>  <primary_uri>/news/2007/05/14/index.html</primary_uri>
>
> or the same for any of the metadata like cover_date, name, categories,
> output_channels, keywords, contribs, whatever.
>
> And we could have equivalent setter commands. So maybe something
> more general:
>
>  $ bric_soap story get primary_uri story_1024
> and
>  $ bric_soap story set primary_uri="/blah/index.html" story_1024

Oh, that's nice. You can then also use "get" for the "location" and  
"workflow" examples above. I was just thinking that it'd be better to  
have simple verbs and then adverbs. "get location story_1024" is  
better than "story location story_1024", IMHO.

> I guess another way to think of it is we'd be exposing the full API
> to the SOAP interface.
>
>  $ bric_soap story get_element_type story_1024
>  $ bric_soap story get_container "page" "1" story_1024
>
> (granted, that's not a very good syntax)

I like it, actually.

Best,

David


[prev in list] [next in list] [prev in thread] [next in thread]