OpenAPI Naming Reference

This document describes naming rules for OpenAPI files. All OpenAPI specifications must be kept in GitLab folder structure. We have three main scenarios:

1. Standard API written in core systems

They are stored in the git project in “openapi/base” folder. Mainly we keep one OpenAPI file per all standard APIs. There is exception is CRM. API specification for CRM is kept separately as we want to have it described but we do not plan to expose it to the customers.

File name pattern: openapi/base/{version}/iptor-{backend application}-api.json

where:

• {version} = v1
• {backend application} = erp

Currently tha OpenAPI specification is in file: openapi/base/v1/iptor-erp-api.json

2. API developed for customers (Cloud-Private only)

They are stored in the git project in “openapi/{customer name}” folder.

File name pattern: openapi/{customer name}/{version}/{customer name}-{backend application}-api.json

For example:

• {customer name} = space-x
• {version} = v1
• {backend application} = erp

Then the file name wil be: openapi/space-x/v1/space-x-erp-api.json

3. API developed for on-prem customers

In this case PS project should keep their own OpenAPI specifications in their own Git. We recommend the same file naming rule as above.

File name pattern: ..../{version}/{customer name}-{backend application}-api.json

For example:

• {customer name} = space-x
• {version} = v1
• {backend application} = erp

Then the file name will be: …/v1/space-x-erp-api.json

Reserved names

There are two OpenAPI specifications which we use in Aperio (API Bridge). They are part of API Bridge repository.

• aperioCore.json - This OpenAPI file describes core functionality of API Bridge like health, admin, rpc endpoints
• aperioTest.json - This OpenAPI file describes special test API endpoints which can be used to test API Bridge itself.