Platform Portal guide

Standards and guidelines for APIs and events

APIs and events should meet the Standards and Guidelines outlined by architecture. In line with these standards, the below requirements are mandatory for users to identify and understand your API. All descriptions must be user-friendly and consumable by the end user and should take the shortest form possible.

1. Response statuses with descriptions (2xx and 500 at a minimum)

2. Tags and properties (Internal Portal: Domain tag and team property. External Portal: Tag for Product, User Type & Solution and team property, you can find the relevant domain to your team here.)

3. OperationId field (In UpperCamelCase e.g. RetrieveSpendOptions)

4. Title, endpoint, and parameter descriptions

5. User friendly schema names (UpperCamelCase and max 50 characters)

6. Servers and Description of Servers for Staging and Production on NDC and NDT environments (and Dev for Internal APIs)

7. URLs without version numbers or /api

8. Version numbers should use the format “1.0” (not 1.0.0, v1 or others).

9. Titles must be user-friendly with alphabetic characters only, capitalized initial letters, and spaces between words. Titles must not contain ‘NewDay’ or partner names, version numbers, or the term ‘API’ as these are implicit.

10. Response examples for all response statuses, responses should be formatted in the following format so they render correctly, like the example here:

If necessary you can use HTML tags or markdown to format the descriptions. This can be useful for adding lists of bolded text.

Allowed HTML tags are:

• <b> for bold
• <i> for italics
• <ul> for unordered lists
• <ol> for ordered lists
• <li> for list items
• <br> for line breaks

You also can use markdown:

• ** for bold
• * for italics
• - for unordered lists

Requirements for internal APIs and events

The following steps should be considered when uploading an internal API or event to the portal:

1. Domain pages: When uploading an internal API or making changes to an existing API, the related domain page file must be updated. Use the existing format in file to document the new or updated API in the product grid.
2. API Design Review: All APIs must go through the design review process before going live, all info here: API Design Review
3. Product Narrative Content: Your API must be accompanied by a product narrative content page to reduce the manual invention needed for our internal users to understand our APIs. All information can be found in the dedicated section below.

Requirements for external APIs and events

Before an API can go external, it must go through our quality-checking process. This is key to keep our users happy as our external portal is regularly used by multiple external clients and as a tool in our sales process.

1. Changelogging: When uploading an external API or making changes to an existing API, the changelog.mdx file is updated automatically. When in doubt feel free to reach out and request additional changes.
2. API Design Review: All APIs must go through the design review process before going live, all info here: API Design Review
3. Peer Reviewing: Your API spec and product narrative content pages (info detailed below) must be reviewed by the following people: Platform Portal PO, Client Solutions, Digital Archicturecture and Principal Engineering (this process can be organised by the Platform Portal PO if you let them know).
4. Product Narrative Content: Your API must be accompanied by a product narrative content page to reduce the manual invention needed for our external users to understand our APIs. All information can be found in the dedicated section below.

Your API is rendered on the portal via an OpenAPI spec, an AsyncAPI (events) spec or a combination of the two. You can upload your files from your own GitHub repository and automate the PR to our repository using the GitHub Action provided below. If you don’t have access to our repo, contact your Engineering Manager.

This GitHub Action automatically validates your API specs against NewDay’s standards, checks for differences between the updated spec and the old version, and updates the content repo with the new spec.

Step-by-step guide

While using the GitHub Action, you will need the following information:

Usage example

Once we have merged your changes, they should update on the portal once we have done a release (usually done twice a week).

Troubleshooting

• [object Object]

  Ensure that the file is available during the run. Check that:

  • The file path is correct in your repository.
  • If the spec is generated during the workflow, the step generating it runs before the upload step.
  • If using actions/checkout with a path parameter, update file paths to include the prefix.

• [object Object]

  The action validates specs against NewDay's API guidelines. By default, failing standards validation does not result in action failure. If this is not expected behaviour, ensure that your throw_on_error code is not set to true.

• [object Object]

  By default, the upload only occurs when a PR is merged into main. If you're running the workflow on another event (e.g., a push, a tag, or a scheduled run), you need to specify an explicit upload condition using the upload input.
  
  
  As a last resort, you can set upload to true, but we recommend defining a more specific condition to avoid accidental uploads.

• [object Object]

  Check that:

  • Your PR was merged to main, as by default uploads only happen on main.
  • Your workflow ran successfully (check the logs in GitHub Actions).
  • You set publish: true if you intended for it to go live immediately. Otherwise, it remains in the dev environment.
  • The Portal release process has run — updates usually happen twice a week.

• [object Object]

  Ensure that:

  • The tags are valid and match exactly as listed in tags.json.
  • The correct format is used (e.g., separate multiple tags with commas, and avoid extra spaces).
  • Each file you upload has corresponding tags, as missing tags can prevent processing.

• [object Object]

  By default, the action creates a PR in the content repository for approval. If auto-merging is expected:

  • Check if the branch protection rules require approvals.
  • Ensure the GitHub token has the right permissions (contents: write required).
  • If automation is expected, confirm that branch policies allow auto-merging.

• [object Object]

  Make sure that:

  • You are using the correct token: ORGANISATION_PAT_DEVPORTALCONTENT.
  • The token has write access to the content repository.
  • Your repo has permission to trigger workflows in the target repo.

Updating APIs

If anything changes about an API, the specs should be uploaded to the portal with the relevant changes, it is key for users that we ensure the Platform Portal is up to date with the latest information. If an internal API changes team or domain, all services should be updated so their specs are tagged to the correct team or domain.

Versioning

1. Minor Versions: These changes are non-breaking and should replace older minor versions upon upload to the portal. For example, if a team is on version 1.0 and makes changes to add support for more fields, the version they upload should be 1.1, and the previous version is replaced.

2. Major Versions: These changes are breaking. Multiple major versions can coexist, allowing support for customers on different major versions simultaneously. Version control is administered via the content repository as follows:

   • Older versions must be marked with a specific version in their filenames. For instance, the latest version specifications are labeled as swagger.json, while previous versions need to include a version identifier in their filenames, such as swagger_v1.json.
   • When teams add spec files with the specified file naming to the content repository, older specs are rendered on the portal under a new URL, such as /api-products/core-credit/core-credit/archive/4.6/reference with the latest version displayed by default. All older versions are available in the archive dropdown.

Deprecating APIs, endpoints and fields

If you have an old version of an API or a legacy service on the portal, you will want to remove it to avoid confusion with users. To deprecate an API you need to set the pub ready settings to false, this will send the API to dev. This means it can be recovered if needed but it won’t display on the live version of the portal. If you only want to deprecate an endpoint or parameter you can use the native deprecated field in Open API, this will render ‘deprecated’ banners next to the endpoint or paramter on the portal.

If you have an API that you want to move users off, you should mark every endpoint as deprecated as below. This will mark the API as deprecated and will help to communicate the APIs status to users.

The endpoints and parameters can also be deprecated using the native Open API deprecated flag. This will render a deprecated banner next to the endpoint on the portal.

Overview

Product narrative content pages are pages that take the MDX format and are designed to explain an API, Event System or Channel service, these can be used on internal or external APIs but the format is slightly different.

1. To draft your product narrative content, we recommend using the Microsoft Copilot GPT-4 AI model. Start by feeding the AI model information about your service. Then prompt the model to answer the questions below.
2. Use this text as your starting point and draft your product narrative content information in plain text. This text can be pulled in a word document, confluence page or any other method you wish.
3. Once this is ready, send it for review by a member of the Platform Portal team. For external services, the page must be reviewed by the following people: Client Solutions, Digital Archicturecture and Principal Engineering (this process can be organised by the Platform Portal PO if you let them know).

Structuring your product narrative content for internal

Section 1 – Overview This section explains the service in a few sentences as high-level information.

Section 2 – Benefits Describe the functionality of the service, it’s capabilities and use cases. Describe which services it interacts with and what products it contributes to.

Section 3 – Authentication Describe how a user can become authenticated to use the service.

Section 4 – Intended Audience Describe who the consumers of the service are.

Structuring your product narrative content for external

Section 1 – Overview This section explains the service in a few sentences as high-level information. Section 2 – Non-technical Info Describe the functionality of the service from the perspective of ‘what does this enable you to do’ – think from the point of view of a Product Owner. For APIs, this section should include information on each endpoint or multi-endpoint capabilities as well as a description of the whole API capabilities. It is key that information about how this service interacts with our other services is included, the focus of this piece is your API but the context of the wider customer journey will help our customers understand the use cases.

Section 3 – Technical Info Describe the functionality of the service from the perspective of ‘how does the service work’ – think from the point of view of a Developer. Explain any customisations, statuses, or any other technical information that you think might be needed.

At the bottom of your page, you must put the standard ‘Getting started with NewDay’ and ‘Still have questions?’ content (you can copy this from the mdx file of an existing API, like the example below).

Example: NewDay eKYC API in portal and NewDay eKYC API in Github.

product narrative content should be customer and lender agnostic as we are developing a platform. Make sure to tailor your content with language that does not mention company names where possible. Consider whether your content will need to be reviewed by any other stakeholders before coming to us (e.g. Legal, Brand).

If you need any icons, images or diagrams, request them from the Platform Portal Team by raising a ticket on your board with the linked Issue set to ‘is contained by’. Then select ‘External DevPortal Content - DEVP-5’ or ‘Internal DevPortal Content - DEVP-6’ depending on which portal you will be uploading to. This Jira method means we can both track the progress of your content as it will be on both yours and our boards.

Using MDX to format your Product Narrative Page

To convert your plain text product narrative content into a renderable form, you will need to use MDX. We have created a full guide on how to use MDX.

The guide has code examples of the different components you may want to use such as a bullet point list. The easiest way to navigate it is by copying and pasting sections of this code and adapting it with your plain text content.

Once you have developed an MDX file, you can view it using our previewer tool. To upload your MDX file, follow the same process as for uploading a spec (above).

Things to note while using MDX:

1. The right-hand navigation bar is rendered when you set right-nav to true, this will generate from the ‘H2’ heading sections.

2. You will have to set pub-ready to true/false to show if your content is ready to be published or not.

3. You will need to add a page title and description.

4. For icons within MDX, you can use our icons library.

Uploading your mdx content page

To upload your mdx content page, manually upload the file to the Content Repo under the same folder as your API spec with title ‘index.mdx’.