REST API Integrations Overview

Customers may choose to deliver master data to Emburse Enterprise via data feeds or via our REST API web services. An API can be accessed over the Internet and executed on a remote system hosting the requested services. These give flexibility by allowing your organization to pass partial data rather than a feed file containing all data rows, regardless of the number of updates required.

Additionally, if part of an API call fails, you will be notified immediately via an error message, and only the affected part of the transmission will fail—the rest will succeed.

While the technical specifications for each API may be found in Emburse Enterprise's Implementation Toolkit, this article will help you understand how our REST API Integrations work and the best practices for designing them.

REST APIs vs. Data Feeds

The choice between using REST APIs and flat files for data integrations depends on your organization's integration requirements and the characteristics of the data being exchanged, and each option has its advantages and disadvantages. Here are some reasons why you might consider using a REST API instead of sending a data feed:

1. Real-Time Data Access

• REST APIs: Provide real-time access to data. You can send the most up-to-date information whenever needed.
• Data Feeds: Typically represent a snapshot of data at a specific point in time. You need to regenerate or update the files to get the latest information.

2. Ease of Integration

• REST APIs: Are designed for easy integration. They use standard HTTP methods and are language-agnostic, making them accessible to a wide range of programming languages.
• Data Feeds: May require custom parsing logic, and the integration process can be more complex, especially if the data structure changes frequently.

3. Scalability

• REST APIs: Can process larger amounts of data by sending incremental requests until all updates are completed. This is a more scalable approach.
• Data Feeds: Might become unwieldy as data volume increases. Managing large files, especially in distributed environments, can be challenging.

4. Security

• REST APIs: Offer authentication and authorization mechanisms. You can control who accesses the data and what actions they can perform.
• Data Feeds: May require additional security measures like encryption and secure file transfer protocols to protect sensitive information.

5. Versioning and Evolution

• REST APIs: Allow for versioning, making it easier to manage changes in the data structure over time without breaking existing integrations.  
• Data Feeds: Changes to the structure may require manual coordination and communication to ensure compatibility with existing systems.

6. Data Granularity

• REST APIs: Allow you to send and receive specific data elements, providing more precise  control over the information you retrieve. This has advantages when there may be more than one source of data.
• Data Feeds: Often contain all the data, which may result in unnecessary information retrieval and processing.

7. Error Handling and Logging

• REST APIs: Offer standardized error handling, status codes, and logging mechanisms, making it easier to troubleshoot issues.
• Data Feeds: Error handling will need manual oversight since the error logs are sent via email, and debugging issues can be more challenging.

8. Real-Time Notifications

• REST APIs: Enable real-time notifications or callbacks, allowing your system to be informed instantly about issues during transmission.
• Data Feeds: Typically, you need to poll or regularly check for updates, which may not be as timely or efficient.

FAQs

Are there firewalls that need to be opened on the Emburse Enterprise side? 

No.

Can you use a mixture of data feeds and REST APIs?

Yes. For example, Person data can be sent via SFTP and Allocation data can be sent via REST API. However, you can't send data using both methods for a single type, like Entity and Person.

Get Started Using REST APIs

Before your organization can begin using REST APIs, a Emburse Enterprise Implementation team member must enable the resources you would like to use and provide you with your Customer Code. (If your organization is no longer in the Implementation phase, create a Support ticket to request these).

Next, one of your organization's administrators must generate an API key from the API Key Management admin screen in Emburse Enterprise. See API Key Management Admin Screen for complete details.

The combination of the API key and your Customer Code will allow you to make REST API requests to Emburse Enterprise.  

Be sure you are using the correct environment and API key combination. If your organization has a QA/UAT environment and you are testing in that lower environment, make sure you are using the correct URL and API key that was generated in that environment. A Production API key will not work in QA, and a QA API key won't work in Production.

curl --location --request GET 'https://service.chromeriver.com/v4/persons/10000000' \
--header 'x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'customer-code: XXXX' \
--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

Base URLs

• Production: service.chromeriver.com/
• QA/UAT: qa-service.chromeriver.com/

REST API Specifications

To view technical specifications for each Emburse Enterprise API, see the Implementation Toolkit.

Each API has a Swagger page that your technical team can use to better understand the structure of the requests. These should be used in conjunction with the File Integration Specification document mapped during your precon workshops with our Implementation team. Your Emburse Enterprise Implementation team contact or Support can also provide sample cURL requests.

Design Best Practices

The following best practices will help you design your API requests and log errors for effective troubleshooting.

• For Expense and Invoice-specific API best practices, see Expense & Invoice API Design Best Practices.

chain-id

Aways include a unique chain-id on your API requests to Emburse Enterprise. We recommend a GUID (Globally Unique ID). This will help Emburse Enterprise Support troubleshoot when you need to investigate an error.

--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

When should a field be included in a request?

Refer to your File Integration Specification document to better understand which data should be included in specific fields for your organization. In most cases, if you are not using that field or array, it is recommended to exclude it from the request.  

• For example, if you are working on the Person API and are not using the UDF field, do not include a blank array because that will result in a “400 Bad Request” error.

   "udas": [
       {
           "name": "",
           "value": ""
       },

Logging/Error Handling

When you're sending and receiving data from Emburse Enterprise APIs, it is essential to focus on logging strategies that capture the details of these interactions for effective troubleshooting and monitoring.

Below are some specific considerations for handling logs in this context.

• Request and Response Payloads: Log the entire request payload (outgoing data) and the response payload (incoming data) for each API interaction. This is invaluable for diagnosing issues related to data format, content, or unexpected values.
• HTTP Status Codes: Log the HTTP status codes returned by the Emburse Enterprise API. This provides immediate insight into the success or failure of each API call.
• Request and Response Headers: Include relevant headers in your logs, especially those related to authentication, content type, and any custom headers required by the Emburse Enterprise API.
• Timestamps and Durations: Include timestamps in your logs to track the timing of API requests and responses. Additionally, log the duration of each API call to identify performance bottlenecks.
• Logging Errors and Exceptions: Log detailed information about any errors or exceptions that occur during API interactions. Include stack traces and contextual information to aid in debugging.
• Retry Mechanism: If your application implements a retry mechanism for failed API requests, log details about the retries, including the number of attempts and any backoff strategies employed.  Make sure the retry has a limit, typically 1-5. To prevent interruption of your API access, do not enable continuous retry.
• Data Transformation: If your application transforms or maps data before sending or after receiving it from the Emburse Enterprise API, log relevant details to assist in understanding any discrepancies.
• Alerting and Monitoring: Implement alerting based on logs to receive notifications for critical issues. Use log monitoring tools or services to detect patterns and anomalies.
• Contextual Information: Include such context-specific information as the purpose or context of the API call to aid in understanding the logs without needing to refer to the code.
• Integration Points: Clearly log which parts of your application are responsible for making API calls. This helps pinpoint the source of issues in a distributed system.

By paying attention to these considerations, you can build a comprehensive logging strategy that facilitates effective monitoring, troubleshooting, and optimization of your interactions with Emburse Enterprise APIs. Be sure to regularly review and update your logging strategy as your integration evolves.