Integrate DigiFi's API to connect your other systems to DigiFi's platform
Overview Of The DigiFi API
DigiFi's API is organized around REST and uses built-in HTTP features, standard response codes, authentication and verbs, allowing for quick implementation with standard HTTP packages used in all languages. The API accepts requests with a JSON body and returns JSON responses.
DigiFi API supports two API URLs:
- https://api.cloud.digifi.io/ (production)
- https://api.sandbox.digifi.io/ (sandbox)
Important Note!
The https://api.cloud.digifi.io and https://api.sandbox.digifi.io API URLs do not support trailing slashes. For example, a request to https://api.cloud.digifi.io/applications/ (GET) will fail with a 404 status code, but https://api.cloud.digifi.io/applications will pass.
API Authentication
Your organization's API credentials for both Production and Testing Modes can be viewed and managed by navigating to General Settings > Developers > DigiFi API Credentials within DigiFi's platform.
To authenticate a request, you must include your api-key in the request header for all requests (POST, PUT, GET and DELETE).
| Key | Type | Required/Optional | Description |
|---|---|---|---|
api-key | String | Required | Identifier specific to your organization |
IP Address Whitelist
Whitelist IP addresses to increase security and grant network access only to specific IP addresses.
To set up IP address whitelisting navigate to General Settings > Developers > IP Address Whitelist.
Sandbox Environment
If your DigiFi plan includes a sandbox environment, consider the following information to build your applications.
- The Production Environment, accessible via https://api.cloud.digifi.io, serves as the primary hosting space for production organizations.
- The Sandbox Environment, accessible at https://api.sandbox.digifi.io, functions as a specialized environment for non-production organizations.
When building the applications associated with the sandbox organization, use the API collection available in our Developer Guide. While the paths for interaction with the system will remain unchanged, the primary alteration involves substituting "cloud.digifi.io" with "sandbox.digifi.io" in the endpoints. This adjustment facilitates a seamless transition between the two environments while maintaining consistent paths for all interactions.
Response Status Codes
DigiFi's API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 200 range indicate success, codes in the 400 range indicate an error with the request and codes in the 500 range indicate an error with the server.
| Status Code | Status Message | Description |
|---|---|---|
200 | Success | The request processed successfully |
400 | Bad request | The request was incorrectly formed |
401 | Unauthorized | The authentication credentials were incorrect |
404 | Resource not found | The requested resource cannot be found |
500 | Internal server error | There was an error on the server |
Rate Limits
The DigiFi API prioritizes stability and has safeguards to help ensure that extremely rapid bursts of incoming API requests do not prevent normal API requests from processing.
DigiFi's API supports a maximum of 100 requests per second for each DigiFi customer. If you exceed this rate limit, you'll begin receiving error responses with status code 429. Please treat this limit as a maximum and take care to not generate unnecessary load. If you need a higher rate limit for business reasons, please contact us.
We may reduce these rate limits to prevent abuse or, if your volume is consistently at extremely high levels, we may request that you migrate to a private server that we can optimize for your specific workload.
Rate limits ensure uptime and maximize stability.
DigiFi's rate limits are set high enough that normal workflows should rarely exceed these limits. However, rate limits can be exceeded under occur under a variety of conditions that you should consider:
- Running migration or batch-testing operations that require many closely-spaced requests. In these cases, you should try to control the request rate on the client side using queuing or similar methods.
- Accidentally encoding API-based loops that execute constantly and indefinitely. In these cases, you should debug the logical issue on your side.
- Keeping many long-lived requests open can increase the likelihood of rate limiting. Resource-intensive API requests take longer to run and increase the risk that new requests will be rejected. We suggest profiling your DigiFi API requests and watching for lengthy requests to help identify these potential issues.
A common technique for handling rate limits is to build in a retry mechanism for 429 status codes. This mechanism should follow an exponential back-off schedule to reduce request volume.
Idempotent Requests
DigiFi's API supports idempotency, which lets you safely retry API requests without accidentally performing the same operation twice. This can be used to strengthen your integration with DigiFi and reduce the risk that can occur when an API request (from you to DigiFi) was successful but the response was disrupted in transit and therefore did not arrive.
For Example
If you make a POST request to the Create Application API and this is performed successfully but the API response fails to deliver, you don't want to retry your request and have it accidentally create the same application again.
To ensure idempotency when making requests to DigiFi, you need to provide an additional idempotency-key element in the header. This key should be generated by you and must be unique. The method you use for creating this key is up to you, however we suggest UUIDs or other types of random strings with enough length to avoid collisions.
DigiFi's idempotency works by saving the resulting status code and the body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result.
Keys are deleted by DigiFi after 6 hours and a new request is generated if a key is reused after the prior key was deleted.
The POST requests in DigiFi's API accept idempotency keys (PUT, GET and DELETE requests are idempotent by definition).
API Versions
API versioning is a crucial aspect of maintaining compatibility and managing changes in your API. In our system, API versions are represented by dates and you need to include the version information in the api-version request header.
If no API version header is provided, the API will default to the 12/01/2023 version.
As our API evolves, older versions may become deprecated. It's crucial to stay updated with the latest version to benefit from new features and improvements. Deprecated versions will be communicated in our release notes.
You can find the list of all API versions with non-backward-compatible changes on the API Versions page.