A little REST documentation needed, I think
rutt
Registered Users Posts: 6,511 Major grins
The REST interface looks very nice, but I think it would be nicer if you provided (and maintained) just a little more information. I'm thinking of an accurate and complete list of the complex types that the interface can return. For example:
Having such an accurate list makes parsing and creating class instances a breeze with expat. Everything that isn't a complex type is just a field or an element of the containing complex type. But it's important to know when I am building where each contained element is a field named by it's type vs an array where each contained element is just another new cell.
With such a list in hand, it's possible to configure a python parser programatically without any further real knowledge of the interface. I don't think the list is very long right now, but I'm sure you will extend it over time.
Could there be a API call to return just this list? It could be as simple as:
This would allow a python parser to configure itself.
- Categories -- Category array
- Category -- struct
- Albums -- Album array
- Album
- &etc
Having such an accurate list makes parsing and creating class instances a breeze with expat. Everything that isn't a complex type is just a field or an element of the containing complex type. But it's important to know when I am building where each contained element is a field named by it's type vs an array where each contained element is just another new cell.
With such a list in hand, it's possible to configure a python parser programatically without any further real knowledge of the interface. I don't think the list is very long right now, but I'm sure you will extend it over time.
Could there be a API call to return just this list? It could be as simple as:
getRestTypes()
returns:
struct
StructTypes -- array of the names of the tags used for struct types
ArrayTypes -- array of the names of the tags used for array types.
This would allow a python parser to configure itself.
If not now, when?
0
Comments
I don't want to put the cart before the horse.
The REST results are very different between the production and BETA endpoints right now. Once everyone's had their say and we finalize how we want it, I'm sure we'll get into documenting it more.
But again, my priority right now isn't documenting. Strange as it sounds, it makes me more time to document a new method than it does to build it.
Right now, my focus is on broadening the API and getting feedback on it. Once we're into a more stable phase, I'll want to get into the docs and really see what we can do to make it more accessible.
Don
It's actually quite a bit of work. With REST, I hand-generate all the XML output, so I have fine-grained control and knowledge.
With XML-RPC, I'm just passing it arrays with values, and it sometimes does interesting things with those values which I haven't had time to fully understand. I'm sure it's predictable, but writing something formal to define the prediction will take work on my part.
Not to mention that the API is constantly changing and expanding at this stage...
Don
I don't think you are understanding what I want. XML-RPC self documents the types of things (to the n-th degree). I don't need a list of XML-RPC complex objects and arrays. It's REST that I want it for. And you say you have detailed knowledge of this.
In it's current state, yes, I do. Tomorrow all of that will change.
There are just too many elements and changes occuring for me to keep a function up-to-date with what elements are what right now.
Don
Just some clue for parsing. Maybe I'm just missing something about REST that means you don't have to know this in order to make sense of what's coming back? Is so, I'd like to know the secrect.
I guess xml-rpc is solving all these problems for me. But REST does look nice, I'm just having a little trouble getting off the ground with it without these clues.
Well, I suppose I could do this if necessary, and if other people thought this was useful, but it doesn't really seem necessary.
Most XML libraries take an XML tree and turn it into an array with elements and attributes. Each element can, in turn, be an array and contain it's own elements and attributes. You can just iterate through the tree and do whatever processing you want.
One possible view, for example, would be as follows:
<Albums>
<Album id="1">
<Public>0</Public>
</Album>
</Albums>
Which cound be seen as:
$array == ""
$array == 1
$array == 0
Or something similar. AFAIK, most XML libraries just do this, or something similar, for you.
I guess what I'm saying is I'm not sure I see the value in what you're describing, since it doesn't totally matte. Just walk the tree and get values, if it's an array, drill down and get values.
There must be something I'm missing. Sorry, I'm probably being dumb and obtuse.
Don
Expat, which is what python uses, works very differently. You get a callback at the start and end of each element. The callbacks get the attributes as arguments. So when you get the <categories> element callback, you don't know whether to start constructing a structure or an array or add an element to the containing complex data type. With the additional information that categories is an array type, you could know to start constructing an array. Then upon seeing the start of subsequent elements, you know to add them as new elements of the array. An element with no type attribute can be assumed to be atomic.
The alternative is to collect information until the matching element close callback and then decide what kind of element you've seen. But I don't see how to make this work. Let's take your example:
<Albums> <Album id="1"> <Public>0</Public> </Album> </Albums>When I get to the end element callback for Album, I've seen one contained element, Public. How do I know whether this is an array with one element that should be indexed by integers or a structure that should be indexed by field name?
Expat is very popular, if a little low level. Google for "xml parser".
Ok, I can see why you'd want this given expat's behavior (stupid, if you ask me, but you didn't write it
Mind taking that example (and expanding on it, if necessary) and showing me what you'd like to see?
Don
I'd like the example to look like this:
<Albums type="array"> <Album id="1" type="struct"> <Public>0</Public> </Album> </Albums>But let me defend expat. How is any parser without semantic knowlege supposeed to know that Albums is an array, indexed by integers, but Album is a struct indexed by strings instead of an array of Publics? I don't see how to make that decision without just the sort of thing I've been asking for.
Fairly easily, I would think. Just test for if there's one element or more than one:
if(count($array) > 1) {
$elementIsArray = true;
}
else {
$elementIsArray = false;
}
XML is fairly simple on the surface. There are name/value pairs, which may or may not contain more name/value pairs. If they do, it's an array of more name/value pairs, and if not, it's a leaf in the tree which is itself a name/value pair. That's part of XML's power - you often don't need to know where the doc came from, what made it, or how it's structured prior to parsing it.
I'm not sure why expat would require you to have any knowledge of what type of data is in the XML - that sorta defeats the entire purpose. An XML parser should be able to take *any* valid XML and return an array/object/whatever that contains everything nicely organized for you. Most XML doesn't describe what it is in any way.
Don
Does this test work for your example? Albums is an array with one element. Album is a structure with one element. If Albums had more than one element, it might be possible to tell that it is an array because there would be more than one value for the name Album.
I must be being dense.