API Standards

GSCS abides by certain guideline when it comes to updates or changes to existing APIs. See below for additional information.

Non-Breaking Backwards Compatible Changes

You should expect any of the following kind of changes that we make to our APIs to be considered a backwards compatible change:

• Adding new APIs
• Increasing rate limits
• Adding fields to an existing response body or request body
• Adding optional URL query parameters Generally, any addition is considered a backwards compatible update and will not have an upfront communication. These types of updates should be non-breaking/ compatible with existing interfaces and not cause any disruption to calling our APIs.

Breaking Changes

You should expect any of the following kind of changes that we make to our APIs to be considered breaking changes:

• Changing data type of an existing response body or request body
• Changing the data type of URL path or URL query parameters
• Adding mandatory URL query parameters
• Changing datetime format in request body or response body When GSCS implements breaking changes to our APIs, we will do the following:
• We will give advance notice communication with sufficient time to allow out integration partners to be able to adjust on their side accordingly
• If breaking changes are implemented, we will generally change the API version. For example, an API endpoint might go from v1 to v2 if we had to make a breaking change to either the path parameters or the response schema

API Certification Process

These are the steps to connect to our GSCS APIs:

• Paperwork and Documentation: We require certain agreements to be on file before giving UAT or Prod API Access. Our integrations team will work with you to provide relevant documents and answer any questions relating to these documents.
• UAT Testing: Once paperwork is on file, we will provide you access to our testing environment where you can test API calls. You can also log in to a testing level of our advisor portal to view how actions performed via API will appear on the UI.
• UAT Certification: Our Certification process ensures that what you have built complies with our logic and business rules. This generally includes a demo on Zoom of what you have built, with our team validating both the UI and the backend. We also require a PDF with step by step screenshots all the proposed workflows. Our team will work with you on the specifics of what is needed based on your integration.
• Prod Access: After certification, we will provide you API Production access. We will work with you to closely monitor the first few actions performed to ensure that the go-live is seamless.

Health Check

The health check endpoint for our service is GET /api/v2/healthcheck. When making a call to this endpoint, we expect to see a 200 response back, meaning that the application is up.

Timeouts

There are cases in which you may see timeouts. Typically the response codes for these are 502, 503, and 504. If our application is resulting in timeouts, on your side, you can display a message like, "Timeout has occurred at x time for url x". When timeouts occur, please reach out to us, and send the timestamp and url. For debugging, it is also helpful if you send the X-Gw-Request-Id and X-Request-Id response headers, however many times in timeout cases, these response headers fail to be added, so the url and timestamp is sufficient instead.

Internal Server Errors

Whenever our application returns a internal server error with a 500 response code, we send an X-Request-Id response header that we use to debug the issue. In case an API call returns a 500, on your side, you can display a message like "An error occurred. Please provide the support team with request ID x", where x is the value of the X-Request-Id response header. When a 500 occurs, please also reach out to us and provide the X-Request-Id so that our team can debug further.