How do you use API docs?

[tim.smith]

I'm looking for feedback on how you use the PureCloud API docs, specifically what parts are most important and useful to you, and if there's anything missing/frustrating about them. We're working on updating the docs, so please comment below and let me know your thoughts!

---

Do you use the API resource's usage section? If so, which tab?

Do you use the API resource's response schema and/or JSON example?

Do you use the SDK's docs? If so, what's useful? What's painful?

Anything you wish was there but isn't?

[Daniel_Grosso]

Hello Tim.

How are u?

Gathered some feedback from my team. As u know are at the end of our developments (for now) but I can tell u that we used (a lot) ur SDK documentation, the API explorer and the analytics query builder.
In some cases the SDK examples on ur swagger do not match with the api main documentaion and we had to do the math. Example:

https://developer.mypurecloud.ie/api/rest/v2/conversations/index.html#postConversationParticipantCallbacks VS. https://developer.mypurecloud.ie/api/rest/client-libraries/javascript/ConversationsApi.html#getConversationsCallbacks

But, what we really missed the most, was some kind of guide for when u need to build a custom connector. Everything we achieved was by sniffing XHR requests from ur front-end and then reproduce it in ours. Probably no one is going to do that now since u made available the embedded framework...but we did
Kind regards,
Daniel

[tim.smith]

@Daniel_Grosso

In some cases the SDK examples on ur swagger do not match with the api main documentaion and we had to do the math. Example:

https://developer.mypurecloud.ie/api/rest/v2/conversations/index.html#postConversationParticipantCallbacks VS. https://developer.mypurecloud.ie/api/rest/client-libraries/javascript/ConversationsApi.html#getConversationsCallbacks

Appreciate the feedback! Can you be more specific about what's not matching up? I took a quick glance at those docs and the GETs and POSTs match between the API and SDK for those resources.

[Daniel_Grosso]

Hello Tim.

Find it below. I might have sent the wrong links.

var body = {
   "scriptId": "",
   "queueId": "",
   "routingData": {
      "queueId": "",
      "languageId": "",
      "priority": 0,
      "skillIds": [],
      "preferredAgentIds": []
   },
   "callbackUserName": "",
   "callbackNumbers": [],
   "callbackScheduledTime": "",
   "countryCode": "",
   "validateCallbackNumbers": true,
   "data": {}
};

api.postConversationParticipantCallbacks(conversationId, participantId, body).then(function(result){
    //successful call
}).catch(function(error){
    //error while making call
});

VS.

var opts = { 
  'body': {} // Object | 
};
apiInstance.postConversationParticipantCallbacks(conversationId, participantId, opts)
  .then(function() {
    console.log('postConversationParticipantCallbacks returned successfully.');
  })
  .catch(function(err) {
  	console.log('There was a failure calling postConversationParticipantCallbacks');
    console.error(err);
  });

[tim.smith]

Ah, it's the SDK example in the API docs that's incorrect. That is on the list of things to address. Thanks!

[Smith_Rj]

Thanks for soliciting feedback on this :). I'd like more information on API rate limits and which resources require user context. And, generally, more detail on situations and conditions under which endpoints can be used (or not).

[tim.smith]

@Smith_Rj

more information on API rate limits

Can you elaborate on what you'd like to see added to the rate limit documentation?

@Smith_Rj

which resources require user context

APIs that always require a user context will be noted as such in the API docs. Some resources require a user only under certain conditions, like conversation APIs, and therefore are not documented this caveat.

[Smith_Rj]

Hi Tim, I hadn't noticed the addition of the Client Credentials caveat - very helpful. For rate limits, I was referring to per-service limitations since services may have a lower limit than the general gateway limit. Recordings, IIRC, is an example (and GDPR endpoints a more extreme case).

[tim.smith]

@Smith_Rj

per-service limitations since services may have a lower limit than the general gateway limit

The current state is that those will never be advertised; your app must be prepared to handle 429s at any time, regardless of what the general rate limit headers say, and should use some sort of process to slow itself down when it gets rate limited, like exponential backoff. There isn't currently a mechanism to communicate private service limits today, so that request falls under a new feature for the ideas site vs. a documentation effort.