Three Keys to Good APIs - Part 2 - Comprehensiveness and Extensibility

In my previous article on what makes a good API, I wrote about transparency being one of the key factors that make an API easy and effective to use. In this post, I'll be focusing on the other two attributes I look for in a good API - comprehensiveness and extensibility.

Comprehensiveness

Comprehensiveness refers to how well the API covers all the possible data and interactions a given app has. For example, most CRM apps have four main components:

  1. Leads
  2. Contacts
  3. Accounts
  4. Opportunities

Sure, the labels may vary from app to app, but these are the fundamental entities building blocks to most CRMs. When I am researching an integration, I want to make sure that each of these entities is present in the API documentation and I'll have a general bearing on whether the API is comprehensive pretty quickly if I can find one or some of these mentioned.

But that's not all - as I mentioned in the article on transparency, you need to think about what you can DO with all these entities. Most RESTful APIs should make this obvious and provide CRUD (create/read/update/delete) functionality, Therefore, for our CRM app to have a comprehensive API, the hypothetical functionality outline should look like this:

  1. Leads
    1. list or query all leads
    2. get a lead
    3. create a lead
    4. update a lead
    5. delete a lead
  2. Contacts
    1. list/query
    2. get
    3. create
    4. update
    5. delete
  3. Accounts
    1. list/query
    2. get
    3. create
    4. update
    5. delete
  4. Opportunities
    1. list/query
    2. get
    3. create
    4. update
    5. delete

You get the idea, and this is the outline I have in my head when delving into an API for the first time. The closer an API comes to this idealized outline in terms of what functions are offered, the more comprehensive it is. In principle, I approach SOAP APIs with this same mental outline. Sometimes the documentation isn't structured this way, but i keep a checklist of SOAP actions that correspond to each of these method calls. 

It does suprise me at the number of APIs which don't offer comprehensive coverage of their data model. I consider APIs that wholly omit one or more of their fundamental entities from their API (i.e. no "Lead" functionality in a CRM API) to be incomplete. Less glaringly, it's fairly common to see APIs which omit the delete functionality - or perhaps instead offer "soft-delete". This make sense from the standpoint of preserving data, but can sometimes be frustrating - especially when testing data and trying to remove that test data.  

A word about User provisioning. It's fairly rare that apps offer APIs that provision new user accounts. While this can be an extremely useful feature (especially if you're building integrations with an App marketplace (see Apps.com, AppDirect, AppExchange etc.), vendors are trying to balance the reward or richer and seamless user-provisioning capability with security. If you're building a full-fledged app which may be need to be provisioned from an exchange (i.e. not a singleton integration), this factor is more important. From an integration standpoint however, I tend to weigh user-provisioning as less important.

Extensibility

The final leg of the stool is extensibility. Does an API provide a way to do more sophisticated actions than simple get/create/update/delete? How about the ability to store additional data about a particular entity? An extensible API is one that has capabilities that allow developers to either store additional data or use more sophisticated open-ended features (e.g. richer data, deeper queries, webhooks, etc.)

Metadata

When an API provides access to metadata, it's usually a good sign the API is extensible. By metadata, I am referring to the actual "data about data". Let's go back to our CRM example and consider a typical Lead entity. It may have the following attributes:

  1. First Name
  2. Last Name
  3. Title
  4. Email
  5. Mobile Phone
  6. Lead Source

Many apps provide APIs to retrieve all the existing attributes (i.e. metadata) about a specific entity. Why does this impact extensibility? If you are able to dynamically determine what fields can go on an entity, you might be able to use this list to populate a query-building user-interface (for example). 

Custom Fields and Custom Entities

The presence of a metadata API suggests that an app may allows you to create custom attributes that go with a particular entity. This is a hugely beneficial feature when building integrations. One of the most common use cases is to have the ability to store a "linked id" and "last synced date" for an entity. For example, maybe I have a Lead in a CRM system and I need to copy this lead over to a marketing automation platform that also has Leads. However, I don't want to duplicate leads, and I don't want to rely on things like email addresses that may or may not be unique. If I have the ability to create a custom field for a Lead in either app, I can store the other app's lead ID and the timestamp the two records were associated with each other. Extensibility like this is very important for building reliable integrations.

Some apps go even further and allow you to create an entire custom entity. This is more common with online database apps like QuickBasePodio and Zoho Creator, although Salesforce also let you also create custom entities. This capability is very powerful, especially when backed with an API with full CRUD capabilities - you have virtually limitless extensibility in this case.

Webhooks

Webhooks are an integrator's power tool - they provide extension points to have an app "call out" or "trigger" an external HTTP POST at certain processing points. Webhooks are most commonly implemented when entities are created, modified, or both. For example: both Salesforce and Zoho CRM provide a capabilities that let you add webhooks whenever a lead is created or modified. You can then take the data the webhook provides and then perform additional actions at the POST endpoint. Shopify offers some very useful webhook capabilities that take place at meaningful points in the life of an online shopping cart (e.g. "When an Order is Created", "When an Order is Paid", "When an Order is Cancelled", etc.")

If you're a developer, you direct these POSTs to your application. Middleware platforms like itDuzzit/AppConnect make use of webhooks whenever possible to deliver near "magic" integrations. Webhooks are what underly the "when this happens" part of the equation, and then you just wire together the "do this" part yourself.

Webhooks are slowly gaining traction among SaaS vendors, but sadly are still not that common. By my count, only about a quarter of the apps I've worked with offer true webhooks; but more are coming online all the time. It's possible to come up with other triggering solutions without webhooks, but that, dear reader, will be the subject of another blog entry!

Conclusion

Transparency, Comprehensiveness and Extensibility are my three keys to grading out APIs and determining how easy they will be to work with. Transparency is primarily about how an API is structured and whether it's well-documented. Comprehensiveness is a measure of how completely functional it is. Extensibility gives you much more flexibility when building integrations and extending the API data model. 

Admittedly, these are subjective measures. Do these factors resonate with you? I've toyed with the idea of giving letter grades based on the these different factors, and perhaps I will in the future. Send me your comments!