API Quick Reference
JSON Requests and Responses
The Fenergo API is REST based. It contains Command and Query endpoints against our primary business domains and each contain predictable resource-oriented URLs. Our API calls accept JSON-encoded request bodies and return JSON-encoded responses using standard HTTP response codes, authentication, and verbs. Clients can test API interactions on one of their SDLC tenant's without compromising data on production environments.
This documentation will call out common HTTP Request and Responses (as opposite) to highlight how to work with the APIs and you can copy the code blocks using the "copy" link on the top-right.
{
"data": {
"type": "Individual",
"policyJurisdictions": [
"Global"
],
"properties": {
"firstName": {
"type": "Single",
"value": "Luis"
},
"lastName": {
"type": "Single",
"value": "McGrane"
},
"migratedEntityActivated": {
"type": "Single",
"value": "No"
}
}
}
}
Authentication
The Fenergo API uses an access token to authenticate requests. An access token is issued to a UI user when they log on and an API user is issued an access token in exchange for a client credential. Client credentials can be protected by limiting the Scopes they are assigned and these scopes are used to control access to specific APIs from within the broader catalogue. This can only be done at the time of creation and credentials are issued by our Cloud Business Office. Clients have separate Credentials per tenant and should plan to govern production resources in the same way you would protect admin credentials to a sensitive database or other protected resource.
Your API Client Credentials will have the level of access you specify when requesting them from our Cloud Business Office. They can often have many privileges, so be sure to keep them secure! Do not share your Client Credentials in publicly accessible areas such as GitHub, client-side code, or email and secure them using best practices for protecting application resources.
API Access Token
When client credentials are passed to our Identity Server they are exchanged for an access token which is then used in all subsequent API calls. An example of a valid response to a request for an access token can be seen below. Along with the token:
- The expiry time which defaults to 900 seconds (15 minutes)
- The scope available to the token. As can be see the scope in the below token is fenx.all which means this token can be used to access all the available APIs.
{
"access_token": "eyJhbGciOiJSUzI1NXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXxxxxxxxxxxxxXXXXXXXXXXXXXXXUQc-tJDGB0Q04LK0n7-hpGijb3mSOZdj_dqB9ex4IlUT209AnS8p9ZE2pmbSkct7tYQaNilCCAAREl0veBjg4wjHvMAVTsJ-Mamp8Z2ek4GwBvsGnEwi3DVK0UVN-51mIZeMVN5m8ntQguXmckbByAddeoH8tcmaoAQ7CONOEiLqVpOTZkJxCbq1NS4O-2NmpsAe-2jtdlQ-XN7sMhHY5JZdWa83jQ8n1A",
"expires_in": 900,
"token_type": "Bearer",
"scope": "fenx.all"
}
All fenergo API requests are made over HTTPS to the API endpoint provided. Clients can also enable MTLS for their client credentials and this can be done via our Cloud Business Office.
HTTP Response Codes
Fenergo uses conventional HTTP response codes to indicate the success or failure of an API request. In General:
Codes in the 2XX range indicate success.
Codes in the 4XX range indicate an error (e.g., a required parameter was omitted etc.).
Codes in the 5XX range indicate an error with the Fenergo service (However these are rare).
- 200 - OK.
- 202 - Accepted
- 400 - Bad Request perhaps missing a required parameter.
- 401 - Unauthorised No valid access token provided.
- 403 - Forbidden No permissions to perform the request.
- 404 - Not Found The requested resource doesn't exist.
- 429 - Too Many Requests.
- 5xx - Service Errors, (something wrong on the Fenergo side.)
API Request Structure
All of the available Fenergo APIs can be found in the API Catalogue where you will also find links to the Swagger Specs.
GET Requests use the URL structure to access resources with a predictable pattern of GET/RESOURCE_NAME/ for a collection and GET/RESOURCE_NAME/ID for a specific resource.
POST Requests accept a JSON structured request, each API will have its own schema illustrated in the Swagger (Open API specs)
PUT Requests accept a JSON structured request, each API will have its own schema illustrated in the Swagger (Open API specs).
The difference between a PUT and POST is that a PUT request is idempotent. It can be called multiple times and always produce the same result, where as a POST called multiple times would result in creating a resource multiple times (duplicates).
==========================================
POST Body
{
"data": {
"journeyId": "e1809731-77df-4e72-98e7-0d314b7a5151",
"parentDraftId": "4fd71919-b072-44be-a520-ab66009f1171"
}
}
==========================================
PUT Body
{
"data": {
"jurisdictions": [
"string"
],
"entityType": "Individual",
"category": [
"string"
],
"properties": {
"firstName": {
"type": "Single",
"value": "Tom"
},
"dateOfBirth": {
"type": "Single",
"value": "2021-07-15"
}
}
}
}
==========================================
A lot of POST API requests across the Fenergo API are idempotent as they do not create or change any resources, this is because they are used as part of the Query Component of the CQRS pattern and a JSON POST Body is used to pass Query Parameters.
Unique Identifiers
Fenergo makes extensive use of GUIDs (Globally Unique Identifiers) throughout the SaaS platform to identify resources. For example, it is correct to refer to an identifier as an Entity Id or as a Journey Id. There is no notable difference between these identifiers looking at them, Only the context in which they are returned. The response from a call to /entitydatacommand/api/v2/entity will be as follows. The GUID in the id field is an Entity Id.
{
"data": {
"id": "7a400251-5800-4a4e-8da8-83e426f3740f"
},
"messages": null
}
Equally a call to /journeycommand/api/journey-instance to create a Journey Instance will return a response as follows. There are three GUIDs in this response. A Journey Instance Id, Journey Schema Id and an Entity Id.
{
"data": {
"journeyInstanceId": "9a6f6da0-5391-4342-8172-800b875764d2",
"journeySchemaId": "da625c11-888d-4c08-8933-e9c8778a1d89",
"entityId": "38827b19-f9df-41f8-8081-c3875ed532f2"
},
"messages": null
}
A GUID is an acronym that stands for Globally Unique Identifier. They are 128-bit unique reference numbers which are highly unlikely to repeat when generated despite there being no central GUID authority. GUIDs are used because they can be generated before data is saved, resulting in a better response time for clients. It is statistically / computationally highly unlikely for a collision to occur.
API Versioning and Deprecation
As the Fenergo SaaS application evolves, the introduction of new features and updates can require methods to be Deprecated and new API Versions to be released. Within the home page of any of the Swagger Specification Documents (in the API Catalogue) you can select the version dropdown and pick a specific version if they are available.
-
Deprecation of Methods will only happen where a method has been superseded by better more capable functionality. For compatibility reasons, deprecated methods will continue to be supported for at least Three Major Releases.
-
API Versions will only be introduced where either a breaking change is required to existing methods or sufficiently new or different functionality is introduced to warrant a major release.
Release notes and an API changes-log are available from Release Notes Overview for clients to wish to monitor and stay on top of updates. Also, Fenergo monitor client use of APIs and if client use of a method or API Version which is being decommissioned is noticed, we will reach out to nominated contact
File Uploads and Secure URLs
Fenergo uses AWS S3 to store documents that clients upload against Entities. Rather than upload files as binary attachments through the API Gateway (which has a file size limit), the pattern to follow is to call an API which accepts document Metadata and returns a Secure URL. This is a short-lived pre authenticated link to an S3 location which needs to be used within 7 seconds. (intention is that its a system to system interaction).
Illustrated here is an example response from a call against /documentmanagementcommand/api/v2/documentmanagement to upload a document against a Legal Entity.
Once a consuming system processes this response and reads the signedUrlToUpload, that value can be used to make a PUT request and Upload a document.
{
"data": {
"id": "7943d6f4-c478-49bd-9152-aa3e9f3f3cc8",
"documentRequirementIds": null,
"documentDataKey": null,
"documentType": "Account Opening Form",
"status": "Processing",
"signedUrlToUpload": "https://docmanagement-URL-aws4_request\u0026X-Amz-Date=20220703T101935Z\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=c511523b6f82bd71e598952210773520b2447e7ec45870540e54029328f7a611"
},
"messages": null
}
API Changelog
Updates to our APIs and product changes can be found in the API Changelog Section of our Release Notes. Click Here to Visit Our Changelog
API Performance and Throttling
As part of the Fenergo SDLC, and the service offered to consumers, The SaaS engineering team conduct performance reviews of all components within the application on an ongoing basis. Automated testing is conducted on new features as they are developed, collective testing is conducted as code updates join the broader codebase, and testing is conducted in load tested control environments. From a consumer standpoint users are largely concerned with Response Time. We take two perspectives on how we communicate response time performance.
Contract Obligations - Which is the upper bound response time we commit to, for how long APIs will take to respond, These are quoted within client contracts.
- Command APIs - Will Respond within 2 Seconds.
- Query APIs - Will Respond within 1 Second.
90th Percentile Response - A Real World expected response for 90% of the APIs when tested under load. These are closer to what consumers experience when working with our APIs.
- Command APIs - 90% of responses between 80ms and 350ms
- Query APIs - 90% of responses between 50 and 250ms
Simply put different APIs perform different functions so no universal measurement can be given. Performance optimisations and improvements are continuously being introduced to production and Consumers should also conduct their own testing.
Clients should be aware that the following domains have standard throttling applied to protect performance for all clients. In the event of exceeding the throttling limits, a HTTP 429 response will be returned for API Calls.
- Entity Data Command API
- Journey Command API
- Event Ingress API