The CMC RestAPI is a powerful, advanced feature that potentially offers a lot of added value for your clients. Providing your clients with API access can also improve their quality of service, differentiate you from competition, and lead to custom integrations that aid retention (make clients “sticky”). Selling and marketing API access to your clients presents a hurdle for many experienced account managers and sales representatives, however, as they may be confronted with questions about abilities and features of the API that are outside their usual area of expertise. It doesn’t take a degree in computer science to be able to communicate the value of API access to your customers, but it does require a little bit of knowledge about how REST APIs work and what they’re generally used for. Startel is here to help, with this rundown on a lot of the common terminology around APIs, and what it means in relation to the Startel CMC RestAPI.
By definition, a REST API has four attributes:
- Identification of resources
- Manipulation of resources
- Self-descriptive messages and
- Hypermedia as the engine of application state
“Resources” in this context is the data in the CMC that you want to find or manipulate (change), “messages” means the data the API server sends back, and “self-descriptive” means it’s structured in a way that lets human beings and software both parse out what the data means and how to use it. “Hypermedia as the engine of application state” is just a fancy way to say “the server doesn’t keep track of sessions, you have to present a token with each request to verify your identity” – that makes REST APIs more scalable than other, older types of APIs that managed each user’s session at the server level.
While the REST API definition says data has to be structured in a meaningful way, it doesn’t specify exactly how. A common choice is currently JSON, which overtook XML as the “data structure du jour” in the recent past. The CMC RestAPI uses the JSON data format to structure responses and fulfill the “self-descriptive messages” requirement.
Since Startel’s CMC RestAPI has all four of these attributes, it can be described as “RESTful.” While RESTful doesn’t necessarily mean HTTP (internet) based, that’s usually strongly implied. It’s true in Startel’s case, as well, since HTTP requests are the method by which you communicate with the API. A lot of times these are referred to as “web” or “web-based” APIs in consumer-facing contexts. This means the CMC RestAPI is “a RESTful web API.”
Because the output is in JSON, the CMC RestAPI can be described as a “JSON API.” For complex queries and actions (like creating new IntelliForms) it also expects JSON as the input. This input is referred to as a “JSON-RPC”, so that’s another term you may encounter. The CMC RestAPI is “a RESTful web API that utilizes JSON and JSON-RPC.”
APIs are often also described as “open”, “internal”, or “partner.” Rarely does an API fit squarely in those categories, however. Whether the Startel CMC RestAPI can be described by any of those terms depends heavily on if and how you decide to give your clients access to it.
To illustrate:
- You use Zapier to create a new lead in your Salesforce account every time an agent saves a ‘New Prospect’ form on your internal client. Now, you’re using it as an Internal API. “Internal” means it’s intended for use by a single organization – yours!
- You’ve got a client that wants to build software to create and dispatch IntelliForms on their account, so you charge them a monthly recurring fee for API access. Now, it’s a Partner API. Partner APIs are intended to facilitate communication between multiple organizations – business partners – in this case, you and your client. Using the CMC RestAPI as a partner API and charging your client for access is one of the most direct ways to turn it into a revenue stream.
- Technically, it could be an Open API if you wanted to provide access to the general public, but that’s not what Startel would intend or recommend.
So, the CMC RestAPI is best suited to being an Internal or Partner API, and while it could be used as an Open API, it wasn’t designed to be. That means the “most precise” description is “a RESTful web API utilizing JSON/JSON-RPC intended for use as an Internal or Partner Web API to the CMC.” The folks involved with your marketing probably wouldn’t like the sound of that – it doesn’t exactly “roll off the tongue.” Generally, just “RESTful Partner API” is enough to infer the rest, and now you have the knowledge to “fill in the blanks” if pressed for detail.
Recent Comments