Pre-defined API basepaths
The API basepaths are globally unique within the API Management platform. To avoid collisions, the basepath assigned to an API published to the LKAB API Management platform, need to conform with the pre-defined set of basepaths in this document, and be unique within the API Catalog.
Assignement of API basepath is part of the onboarding process when a new API are about to be published to the API Management platform, agreed upon between API owner and the API Management team.
The agreed and assigned API basepath SHOULD be documented along with the assigned API Id in the API Catalog before first deployment.
Changes to the API basepath SHOULD be discussed and agreed with the API Management team, and then documented in API Catalog before re-deployment.
This document will be updated as the need for new basepaths emerges.
Basepath naming guide
The ambition is to use the basepath as a logical context wherever possible, and there might be contexts where there is a need to add one or more "subpaths" to make distinction easier and avoid collisions.
Some common rules (as basepaths are part of the URL):
- Use lower-case
- Use 'dash' (
-) as separator if needed, never use 'dots' (.), and never use whitespace in the basepath - Use english names
- Avoid special characters, e.g. swedish å, ä, ö
- Avoid everything that could break an URL
More recommendations:
- Avoid place names, e.g. 'kiruna'. However, there may be cases of use where place names are suitable as subpaths.
- Avoid business area names. They tend to change with reorganizations.
- A majority of systems exist to support specific processes, and in those cases the process name may be suitable as a basepath or subpath
An example. The InfoPlus.21 (IP21) system stores time series for sensors that span many places, organizations, business areas and processes, as well as all kind of different sensors, thus we avoid those as being part of the basepath. The common denotator is sensor-data, hence the IP21 API will be assigned the basepath: /sensor-data/ip21.
Pre-defined basepaths
This table will be updated as the need for new basepath and corresponding subpath emerges.
Consult with, and if necessary update, this table when deciding on the basepath for a new api.
| Basepath | Subpath | Description | Other info | API visibility |
|---|---|---|---|---|
| /external | Deprecated | Do not use this basepath | public | |
| /internal | Only available from internal network. | private | ||
| /integration | Peer-to-peer integrations | private | ||
| /maintenance | Cross-process and cross-business | public | ||
| /sensor-data | Cross-process and cross-business | public | ||
| /quality | E.g. analyzes of product quality. | Cross-process | public | |
| /logistics | public | |||
| /mining | Mining related | Use subpaths for fine-grained grouping | public | |
| /mining | /development | public | ||
| /mining | /design | public | ||
| /mining | /transport | public | ||
| /mining | /production | public | ||
| /mining | /production/loading | public | ||
| /processing | Processing related | Use subpaths for fine-grained grouping | public | |
| /communications | Branding and internal/external info | public | ||
| /development | Development related. E.e. Specifications, samples, code | Cross-process | public |
API Visibility
The API Visibility column indicates if your API will be visible in the API Portal or not.
All access to consume the your API are granted by you, as API Owner, whether the API is private or public.
public
API visibility public means that the API will be visible in the API Portal for signed in users.
To publish your API as public you add it to the LOMI product in your API pipeline (there is a template for that).
private
API visibility private means that the API will not be visible in the API Portal for signed in users.
To publish your API as private, do not add it to the LOMI product in your API pipeline.
If you prefix your API with the/internal basepath, only clients from the LKAB network will be able to access the API.
NOTE! You, as an API Owner, still have to grant the client (app registration) access permissions.