Integrating External APIs with ServiceNow: Best Practices?

[Avjyan]

Hello fellow developers!

I'm Hakob Avyan, I've been tasked with integrating an external RESTful API into our ServiceNow instance. While I have experience working with APIs in other platforms, this is my first deep dive into ServiceNow integrations.

1. Authentication: The external service uses OAuth 2.0. Are there any best practices or common pitfalls I should be aware of when setting this up in ServiceNow?

2. Data Synchronization: We'll be pulling in a significant amount of data. Are there any recommendations on how frequently to sync, or tools within ServiceNow that can help manage and monitor the data flow?

3. Error Handling: What are the best strategies for handling potential errors, especially when dealing with large volumes of data or rate-limited APIs?

I'd love to hear your experiences, best practices, or any resources you might recommend. Also, if anyone has worked on a similar integration and is open to a deeper discussion or collaboration, please let me know!

Thank you in advance for your insights!

[Bert_c1]

Hi Avjyan,

You can start here:

https://docs.servicenow.com/search?q=REST%20API

And Type "REST" in the Navigation Menu Search for OOB examples.

[DineshS]

Hi @Avjyan , may be worth clarifying if ServiceNow is the API consumer or the provider. From your 3rd question, I am assuming you were referring to ServiceNow as the provider. For rate limiting, SN uses a hourly rate limit which I personally think isn't good enough, other systems use TPS(transactions per second). So for example, if the hourly limit was set to 10,000 in ServiceNow, and if the API was called 9000 times in the first one minute, the rate limit isn't yet breached but it may have impacted the platform already.  Check this page for rate limit config - https://docs.servicenow.com/csh?topicname=inbound-REST-API-rate-limiting.html&version=latest

There is no rate limit feature for outbound calls from SN, ie when ServiceNow is the API consumer.

For large volumes of data,

• use pagination to retrieve set number of records at a time. I would also recommend that the consumer keeps this value as configurable, so it can be modified as needed, especially when there is a negative impact on the SN platform. Refer this KB for details - https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0727636
• ensure to return only those fields that are required by the consumer. For example, if the consumer is querying on incidents and is interested only in incident number and state, ensure the API consumer specifies them against the query parameter sysparm_fields

sysparm_fields=number,state​

[Amit Gujarathi]

Hi @Avjyan ,
I trust you are doing fine.
Please find below best practices which we use in our project :

Here are some best practices and considerations for the areas you've highlighted:

Authentication with OAuth 2.0

1. Service Account vs. User Account: Determine whether you'll use a service account (recommended for system-to-system interactions) or individual user accounts for authentication.
2. Credential Storage: Utilize ServiceNow's built-in encrypted storage to securely store OAuth tokens and credentials.
3. Token Management: Implement token refresh logic in your integration to handle token expiration seamlessly.
4. Testing: Thoroughly test authentication under different scenarios, including token expiration and invalid credentials.

Data Synchronization

1. Sync Frequency: The frequency depends on the data volatility and business requirements. For frequently changing data, consider near-real-time synchronization. For more static data, less frequent syncs might suffice.
2. Import Sets and Transform Maps: Leverage these ServiceNow tools for importing and transforming external data into ServiceNow tables.
3. Scheduled Jobs: Use scheduled jobs in ServiceNow to automate the data sync process at defined intervals.
4. Monitoring and Alerts: Set up monitoring for your integration to track data flow and performance. Use alerts to notify relevant teams of any synchronization issues.

Error Handling

1. Robust Logging: Implement comprehensive logging for tracking successes and failures in data processing.
2. Retry Mechanisms: For transient errors, especially with rate-limited APIs, implement a retry mechanism with exponential backoff.
3. Alerting on Errors: Set up alerts for critical errors so they can be addressed promptly.
4. Rate Limit Handling: Be aware of the API's rate limits and design your integration to stay within these limits. Consider implementing a queuing mechanism if necessary.