Here’s an idea I had today based on a conversation I had with some of the other SharePoint MVPs: expose the REST endpoints and documentation right in the UI for those who have the appropriate permissions. It could be a little icon at the bottom of any page where there are relevant end points. All content is security trimmed anyway, so no one is going to see an endpoint they can’t use (though if they can fathom the docs they can know what endpoints there are available).
Think about it:
- You’re on a List Settings page, and you can see the endpoint for that
- You’re on a workflow status page…
- You’re in Central Admin on the Create Site Collection page…
- You’re on a Term Set Administration page…
- You’re on a List View page…
All of the APIs are more obtuse than they need to be. In many cases, the docs are either very long-winded without explaining basic operations or just content stubs. By adding these direct connections from the matching UI pages, it would:
- Satisfy the developer needs for easy to understand documentation
- Educate appropriate [power] users about how to talk to the devs about what they want
- Potentially get telemetry to Microsoft about what people want in the APIs and their docs
There’s far too much of the “I can’t look it up in the dictionary until I know how to spell it already” going on with the APIs in SharePoint in general – going back to the SOAP Web Services and beyond. The platform needs to be more open, not less. Adding these direct links to the REST endpoints and their docs would be an incredibly powerful step in that direction.
What do you think of this idea? It’s mine alone and even if it’s the best idea I’ve ever had (probably not) there no guarantee that it would make any sense to the Product Group. Leave a comment, though, and add your own thoughts about how to make the SharePoint APIs more usable.
If you think this is a good idea, vote for it on the Expose REST Endpoints in the SharePoint UI item on the Office Development UserVoice site.