API Policy
The important things to know when integrating with our API's
Our API policy defines how we build our API resources to enable reliable integrations and long-term usage. Most of the resources offered are REST API's, however this policy applies to all API's consumed by customers.
🤝Compatibility
All FundApps resources offered via an API (REST, code client or anything else) are subject to our compatibility policies. This to ensure all customer integrations will continue to work with our services.
Consistency
All API's will remain consistent in behaviour from the point in time at which they are made available. In the event a resource behaviour needs to change:
- New Resource: A new resource will be introduced (e.g.
GET /new-resource
) - New Version: A new version will be introduce (see 'Versioning' below)
In the event of a critical security vulnerability, we may change the behaviour of an API without notice to carry out mitigation
Authentication
FundApps services may use separate forms of authentication in order to best suit the needs of the service. Most of our services allow for authentication using the basic credentials of an API
user registered with FundApps, however this will change depending on the requirements of the service.
- Basic Authentication: To authenticate to the API via Basic Authentication over HTTPS, a administrator from your organisation must create a user with the role
API
for this purpose. You must authenticate for all requests. Note: Please ensure you create a separate user for the API as if you use an existing user's account, as soon as they change their password the API upload will fail.
Any changes to in authenticating to a service will be treated as a deprecation
Versioning
In the event of a breaking change, a new version of a resource will be introduced. A breaking change is defined as:
- Change in field name or resource path: The name of a field changes or the location of the field within the schema changes location.
- Change in data type of resource: The data type of a resource changes (e.g.
integer
tostring
) - Change in API request: The (HTTP) method by which the resource is requested changes.
A new field being introduced to the output does not constitute a breaking change.
Each service will use its own method of versioning which will take one of two forms:
- Change of version in URL: Wherever the URL contains a version resource in its path (
/v1/
), the version will be incremented (v2
). If the version is not previously defined, a new version indicator may be included in the path, starting at version 2. - Change of version in Header: A custom header (e.g.
Api-Version
) may be used to control versions. In the event the header was not previously included, any request will default to version 1 and version 2 will need to be specified in the header.
Deprecation
Any FundApps API resource subject to deprecation will be available for a 3 months deprecation notice period
Our APIs will be given reasonable notice of deprecations. Any deprecated API must be available in its original form for a minimum of 3 months, unless there are critical security vulnerabilities, in which case an API may change to ensure adherence to our security policy (see below).
A deprecation notice will be issued via a notification and any resources will be clearly marked with a deprecation (e.g. (Deprecated)
is specified before the resource within our API references)
💽Data
Data Limits
Each API has a distinct data size limit for uploading requests. The default is 10MB, unless further information is given in the open API specification (e.g. Position File Upload which supports 200MB).
For endpoints which accept a file upload, where possible, a method of uploading data in a .zip
or .gzip
file will be provided.
🔐 Security
All API's are subject to the FundApps Security Policy, as defined in the FundApps Policy Portal.
Updated 5 months ago