I regularly find myself shining a spotlight on the SalesForce API, holding it up as an example of why APIs matter. They are the OG API pioneer, and 20 years later they are still rocking it with their APIs. With that said, their API approach is in desperate need of some modernization. I don’t want to shame the folks operating things now, they’ve done a great job, but as someone who looks at a lot of APIs, every time I have to roll up my sleeves and implement an integration with SalesForce, I find it all to be much more cumbersome than it should to be.
After almost 20 years, the value is evident within the SaleSforce REST API, but there are so many other supporting APIs, SDKs, and other resources, that the core Force.com REST API seems to get lots in the shuffle. Not that my opinion matters all that much, but I wanted to take a few moments to share my views, in hopes someone at SalesForce might read this, or at the very least help other API think more deeply about how to keep their APIs modern and useful for their consumers--here are a handful of things I’d suggest the SalesForce developer community consider as they look towards the future.
- Information - I have integrated with SalesForce over 50 times, and even though I know what I need, I always get lost wading through the volume of information that exists within the developer portal. It takes me a click, a significant amount of scrolling, and a second click to get to the REST API documentation that I need. I get it, there is an amazing number of resources available, but I’m afraid the core value of the Force.com REST API gets lost in the shuffle. I know what I need and I get lost, I can only imagine how confusing it is for new developers.
- Authentication - The OAuth implementation and documentation is just too verbose. I can always find the core set of values I need to configure when setting up my application, but finding where and how to do it usually takes me about 1-2 hours each time I have to setup OAuth. Take a look at the OAuth approach for other leading API providers, then get to work distilling things down, making it dead simple to add an application, and know how to setup, then put the more detailed information one-click behind the scenes.
- Design - While extremely robust, the design of the SalesForce API is pretty old school. Calling everything sObject, and making us all look up our objects to build our own paths is a pretty dated approach to getting things done. Take a look at the Postman Collection I’ve created where I’ve merged the objects with the API paths, making things much more intuitive to new users who might not get what all this sObject talk is about. Once you know how things work you eventually find your way, but the challenge for me always is introduced when I have to put down for a while, come back, and re-learn all of the complexities—the design of the API should just do this work for me.
- Documentation - The documentation for the API is too verbose, and takes too many clicks to get through it all. I recommend modernizing the API documentation by maintaining your own Postman collection or OpenAPI definition and publish more modern API documentation from these machine readable artifacts. Invest the time and energy in crafting short, concise, and meaningful summaries and descriptions for each path, and make sure they have all the properties, enums, and other elements well defined and kept up to date.
I’ll stop there. I could go on for days, but I feel like if SalesForce invested in these four areas it would completely transform their API on boarding and integration process. This all could be done without impact the evolution and delivery of the API, just change up how you present what is possible. Then you could get to work standardizing this approach across all of the available SalesForce API. I can’t help but think that if the presentation for the core Force.com REST API was simplified and brought front and center within the portal, it would change the entire tone of the community. There is so much value in there that could be brought out pretty easily with some information architecture, and leverage modern API definitions and documentation publishing solutions.
I’m not saying you should get rid of all the rich documentation that exists, just don’t make me wade through it all when integrating with the SalesForce API. Just give me exactly what I need to sign up for an account, setup authentication, and get to work integrating with all the available APIs. If I want more information I will go find it. I recommend the SalesForce API team go spend time within the developer portals of other modern APIs like Stripe, Twilio and others, then invest some cycles in modernizing your approach. I get it, you’ve spent years publishing documentation, and evolving the API to meet the needs of your massive developer community—it can be hard to see the forest for the trees. However, I think with just a little modernization effort, you could reach an entirely new audience, and power entirely new applications and integrations, reducing friction for developers when it comes to understanding what is possible, allowing them to go from zero to sixty in as little time as possible.
If you want to learn more, you can visit the documentation I've published for the SalesForce API, demonstrating how a little design can be applied to the APIs and make them a little more approachable and usable. You can also use the run in Postman button on the documentation, or put to use, help evolve, and fork Postman Collection and OpenAPI definitions for the SalesForce API on GitHub--if you have any questions, submit GitHub issue on the repository.
