Salesforce’s Troubling API Design
Self-documenting is not the same as well-documenting.
Yesterday I was on the receiving end of the Salesforce Data API. It was not pleasant experience. Bewildering developer account setup (I now have ten different e-mails registered), and “cutesy” pirate-themed tutorials aside; the real issue is how the the whole API is presented.
I came to the documentation with a purpose. I wanted to be able to raise and close ‘Cases’ in the service console. I had experimented with doing it in the UI, so I had a pretty good idea of the process involved from a user’s perspective. But what I saw in the reams of developer “help” bore no relation to anything I’d seen before.
Once I got over the generic information about making authenticated restful requests, I was abandoned. This is because, it is explained, the API is ‘self-describing’. Each type endpoint exposes a describe path that returns a machine (lit. not human) readable schema for the mechanical capabilities of all the fields.
It’s a noble sentiment- to build an API that documents itself. In practice it meant stumbling around blindly calling
GET /describeon any likely looking path; trying to interpret field names and divine behaviours.
To compound the problem, the root of the API is actually the group (lit. type) of the thing you want to work on. This meant that to even start discovering, you would have to be aware that a Case is of the type sObject. It is moments like these that make you aware that for all the usefulness of knowing that sObject.case.Subject is a mutable string with a default value of '', what you’re really hankering for is a commentary.
The experience has been a stark contrast to the Zendesk API I’d recently moved on from. Zendesk has single-page documentation describing (in human, and machine) both the intent behind the data structures and the methods behind the actions.
The Lesson: Without commentary, self-describing APIs are just glorified type definitions.
