Or, what the &%^*ing $^($!!
I've had the great misfortune to have been working with Sharepoint for the past few weeks, using the REST interface to try and pull (and push) data out. Now, I'm doing this in PHP, so I know all about inconsistency and pain, but I think Sharepoint may even outdo PHP for obscurity. Here's a list of the stuff I can remember off the top of my head, starting with Sharepoint 2013:
* Lists in Sharepoint have ids, which are GUIDs. But items in the list have ids that are sequential(ish). But those items also have GUIDs. However, you can't use the GUIDs to look up items in the list. There is no way to look up an item purely using its GUID, you need the id of the list it belongs to.
* You can retrieve a list of the Fields being displayed in a list. But, even if some of the fields are built-in ones (checked out by, created on, name etc) they are all of the type "Custom Field". There is no way to differentiate between user-created custom metadata fields and builtin default fields.
* When you retrieve an item's metadata, only the Title is returned, even though Title is a non-mandatory value and is different to Name (which is mandatory).
* For some reason you can't just use a list id in the REST url (http://site/lists/
<id>/) like normal REST interfaces, you need to use http://site/lists(guid
'<id>') (this may be due to the odata specification, I don't know enough about it)
* If a list or file name contains a space, the "ServerRelativeUrl" value returned in any REST requests is an invalid URL as it is not properly URL encoded. But you can't just URL encode the whole string as it may contain valid URL path separators so you have to break it into bits and URL encode each bit before putting it back together.
* When you try to contact the REST interface, if you happen to specify your POST Content-Type as "application/json" instead of "application/json;odata=verbose" you get the very helpful error message "The required version of WcfDataServices is missing". What?
* When you try to add a file, you can't just POST the filedata to the list, you instead need to post it to a default folder called "rootfolder" with extra add parameters:
"MyList")/rootfolder/files/add.." rather than just POSTing to http://site/lists/GetByTitle(
* If you POST content to a list, you must indicate the "type" of the item. The "type" can't just be "SP.ListItem", it's a type specific to the list called "SP.<MyListNameWithoutSpaces>ListItem".
* Even when you first create an item, you need to specify the "concurrency" value If-Match: or the creation will fail.
* If you are POSTing data, you need to provide a "Request Digest" token (presumably this is like a "hidden" form field used by the Sharepoint web interface). If you don't provide it, you get the helpful error: "The security validation for this page is invalid and might be corrupted"
I was then lucky enough to have to support the Sharepoint 2010 REST interface too:
* Of course, you'd think the Sharepoint 2010 REST interface would be somewhat similar to the 2013 one. It is actually completely
different to the 2013 one, although 2013 seems to maintain a backwards compatible version.
* You cannot obtain any information about a list in Sharepoint 2010 other than its name.
* Lists can only be referenced by name in Sharepoint 2010. When you do, the name should have all spaces stripped out (I don't know what happens if you create both "My Sharepoint List" and "MySharepointList").
* Unlike Sharepoint 2013, in 2010 both "Name" and "Title" are returned for a document.
Why yes, I really did need to get that off my chest, thanks for asking.