Technical support on API

Do's and Don'ts when creating an API support ticket

The goal of this article is to provide clear guidelines on the best practices when creating an API ticket. Reporting a problem in the Nmbrs interface is different from reporting a problem in the API and we want to make the communication as smooth as possible with our clients. 

  1. Provide all parameters used in the call that is having problems
  2. Attach Nmbrs application screenshots to explain better what is the problem, when possible
  3. Share the exact error message
  4. Be precise on the problem you're encountering
  5. Don't use generic sentences as description
  6. Limit the amount of images from other applications
  7. Don't send logs generated by the integration partner application

Do's

Provide all parameters used in the call that is having problems

For example, let’s consider the call Address_GetList: it provides three parameters in the header and three parameters in the body. Therefore, the best would be to specify all these parameters when creating a ticket (except the token, due to security reasons). 

  1. Username
  2. Domain
  3. EmployeeId
  4. Period
  5. Year

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Header>
      <AuthHeaderWithDomain
xmlns="https://api.nmbrs.nl/soap/v3/EmployeeService">
         <Username>
string</Username>
         <Token>
string</Token>   
         <Domain>
string</Domain>
  </AuthHeaderWithDomain>
   </soap:Header>
   <soap:Body>
      <Address_GetList xmlns="https://api.nmbrs.nl/soap/v3/EmployeeService">
         <EmployeeId>int</EmployeeId>
         <Period>int</Period>
         <Year>int</Year>
      </Address_GetList>
   </soap:Body>
</soap:Envelope>

Attach Nmbrs screenshots to better explain what is the problem, when possible

For example, we had a bug in the call Contract_GetAll_AllEmployeesByCompany  which was not returning all contracts per employee. 

To better explain the problem, the user provided a screenshot of the contracts in the UI and one of what was returned by the API. Since he also provided the domain and EmployeeId that was missing data, we could easily identify, replicate and then quickly fix the bug. 

Service_interval_details_API_article.pngService_interval_API_output_details.png

If you are getting an error message, share exactly what it says

Many different error messages may be returned by the Nmbrs API. For example, when doing a call, the result below was returned. We have an article with Nmbrs API error codes. Going through this article, it is very easy to see what the problem is and how to fix it. 

Unexpected error messages might appear, and if that is the case, a ticket should be created. Don’t forget to tell us exactly what error message is being returned and to provide all parameters used in the call that is having problems.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <soap:Fault>
         <faultcode>
soap:Server</faultcode>
         <faultstring>
Server was unable to process request. ---&gt; 2004: Unauthorized access</faultstring>
         <detail />
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Be precise on the problem you are having

For example, if you are having problems retrieving data about Schedule, mention specifically which calls are not working as expected. Currently, we have four different calls to return Schedule data:

For better and faster replies from both the support and the development team, it's important to mention exactly which of the calls you are using that is not returning the expected result. 

If you don’t know much about APIs, ask help from your technical team to be able to provide all the information needed

It is hard to explain what the problem is if you have never seen an API call or don’t know how they work. To facilitate communication, it is very useful to request more details from your technical team. Always remember to Provide all parameters used in the call that is having problems.

Don'ts

Use sentences like “API is not working”, “API is slow”, etc. We need to know in which calls you are experiencing problems!

Sentences such as the above are very generic. At the moment we have 200+ calls on the API and it’s important to be specific on exactly which call is not working as expected for us to be able to analyze it. If possible, explaining with some evidence to substantiate it would be best. 

For example, instead of saying that the API is slow, you could say that the call PersonalInfo_Get used to take 2 seconds on average and is now taking 10 seconds. With clear information and a specific call, we are able to analyze in a better way. 

Attach images from other applications than Nmbrs. We cannot investigate other software errors!

When screenshots from applications other than Nmbrs are attached to support tickets, they don’t help us identifying what is the problem to be fixed. Most of the integration partners use the Nmbrs API to connect to their systems. Therefore, they are the ones who know how Nmbrs works and have to make sure their integration is working as expected. 

We don’t have access to the partner's application code, nor do we know how they handle the various responses from Nmbrs. In this situation, please request the partner to contact us with details of what is going wrong in the connection. 

Send logs generated by the integration partner's application

This is very similar to the previous point. An integration partner can create their own code in any programming language, to integrate with the Nmbrs API. If logs from the partner application are attached, we cannot use them to investigate anything. We need the ticket to be precise on the problem that's happening.

Comments

Knowledge base