The API is designed and built according to Equinor's API strategy.

The API is documented in OpenAPI 3.0 format and follows REST principles.

A simple way to test the API is through Postman which is accessible through AccessIT.

The API will use common terminology used across the Oil&Gas industry for the maintenance process. Norsok standard NS-EN 13306 and ISO 14224 are key resource in the naming of resources in the API.

api-version must be present in all request as part of the query string. Requests without API version will be rejected with a HTTP 404 response code. The latest api-version is v1.

Subscription key must be created from Equinor's API Portal for the consumer application and each request must have the HTTP header Ocp-Apim-Subscription-Key present with this value.

The Maintenance API will combine information from various business systems in Equinor used in the maintenance area through one common API.

Currently, the majority of endpoints connect to Equinor's ERP system based on SAP.

The user executing the API requests will need to authenticate with OAuth 2.0 authorization code flow with Equinor Azure AD as the identity provider.

The user needs to exist and have authorization in Equinor's ERP system. Equinor Azure AD affiliated users are not supported as the user does not existing in Equinor's ERP system. In special cases, system to system integration can be setup; see section Client setup->System to system setup for more information.

Applying for access is handled by the internal AccessIT solution and the following roles are required:

• SAP P05: YO900 - OM Mobile Apps & API (SAPP05)
• SAP P03: General Operation & Maintenance roles for P03

Note: YO900 replaces old role YT105. YO900 is normally only required in SAP P05. For SAP P03, it's in most cases covered by general operation & maintenance roles (as they include YO900/ZO900).

Note: If the user should have only display access through the role YO017 - Display role O&M External, they need the YO900 - OM Mobile Apps & API (SAPP03) role in addition.

General operation & maintenance roles depend on the function of the business users. For employees, it's typically YO001 - Display role O&M and YO002 - Operations & Maintenance Executor. For consultants, it's typically YO017 - Display role O&M External and YO011 External - Support Executor. For contractors, the roles are covered through ACM positions assigned and approved by the vendor company (YO301_01 is an example of a role defined for contractors). More information can be found in governing document GL0446 - SAP roles in operation, maintenance and modifications.

For Maintenance API QA environment, consumers will need to apply for same roles in SAP QA systems Q05, Q93 and Q83 (used during planned downtime for Q93). The KB0036937 defines the procedure for applying for roles in the SAP QA environment.

In addition for Maintenance API QA environment, the end-users need to be members of the Equinor Azure AD group APPL OM Notification and Work order QA. Request this access through the #maintenance-api channel of Equinor slack or via Equinor's service managent system service-now.

The API allows you to get mock response for all endpoints if required. This can be useful in special cases. For example if developers from external companies do not have (and should not have) authorization in Equinor's ERP system, they can still interact with the API to see the possibilities.

Add mock-response=true as a query parmeter to the request and the response will be mock data based on the OpenAPI specification.

Maintenance API can be integrated and provide value in solutions such as web applications, mobile apps, Power Apps, commandline scripts and many more. In order to start using Maintenance API, some setup is required. We strive to keep this to a minimum and will assist developers from IT and the business in the necessary setup.

The standard and prefered scenario for using Maintenance API involves OAuth Authorization Code Flow. Here the client application is configured with permission to call the Maintenance API on behalf of the logged on user in Equinor Azure AD. Interaction with the backend ERP system (such as read a failure report or update a work order) is performed with the logged on user and requires that the logged on user has the necessary authorizations.

The following configuration steps needs to be performed for the initial setup:

1. Create client app registration in Equinor Azure AD through portal.azure.com for each environment of your solution. This step requires the Application Developer role in Access IT. See Omnia documentation Application Management in AAD for more information. We recommend one client app registration pr client environment such as dev, qa and production.

2. Create client secrets for your client app registrations

3. Add an API permission for the app registrations towards the Maintenance API. The following API names are used with application id in parenthesis: Maintenance API Dev (0e595101-1f08-4ce0-8684-148b2e2b8e18), Maintenance API Test (25bb4326-cdc1-4048-8306-29d9fe1102a4), Maintenance API QA (ad711600-154b-4ab0-8945-06cba7f10c4b) and Maintenance API Prod (1aee2186-b5f4-445a-bbf2-d28589ccb59a)

4. Create a subscription key from Equinor's API Portal. We recommend first creating the subscription key in the API Portal QA environment, before proceeding with the API Portal Production environment

5. Trigger an authentication request through a http client (such as postman) in order to trigger the consent process of the API permission

6. Contact us at the #maintenance-api channel on slack or create a Github issue for maintenance-api-docs. We would love to hear how you intend to use the API and to allow us to map the subscription key to an application in our operational logging

We recommend using Postman as a tool for experimenting with the API.

In some scenarios, the standard setup does not cover the requirements and there is a need for system to system communication without user interaction. An example of such a scenario is scheduled background jobs.

For Maintenance API system to system integration requires additional setup both in the ERP system and for the client.

In the ERP system, a role supporting the specific client requirements must be established. In addition, a system user with this role will be need to be created.

The client must use the OAuth 2.0 client credentials flow with certificates. In the client credentials flow, the client application will be registered in Equinor Azure AD as an app registration with a client secret. The client must securely store the client secret. The client must also generate a self-signed client certificate and upload the public key to Equinor Azure AD.

The Maintenance API team will assist in the system to system setup if it's necessary for integration. So contact us at the #maintenance-api channel on slack or create a Github issue for maintenance-api-docs.

Microsoft Power Apps is a low-code platform for implementing business functionality. For more information on the usage of Power Apps in Equinor, see the Microsoft Power Platform group at yammer.

In order to simplify the usage of Maintenance API within Equinor Power Apps, our team maintains a custom connector for the API. The custom connector will be kept up to date with the latest functionality in the API.

We also maintain a proof of concept Power App using the Maintenance API custom connector called "Maintenance API - GP Møte Forberedelser".

The following steps are required in order to add the custom connector to an existing Power Apps project:

1. Create a subscription key from Equinor's API Portal. We recommend first creating the subscription key in the API Portal QA environment, before proceeding with the API Portal Production environment

2. Edit the Power App to use. In the data panel, select Add Data, expand connector and add maintenance-api-qa for the QA environment and maintenance-api for the production environment. Power Apps will prompt you to create a connection to the custom connector. For more information see Microsoft documentation Use a custom connector from a Power Apps app

3. MaintenanceAPI object will now be available from formulas in the Power App. We recommend the results of calls to Maintenance API are stored as a collection. As the last mandatory parameter to all calls, Ocp-Apim-Subscription-Key, use the subscription key from step 1.

Below we have provided some example formulas with Maintenance API which can be used from Power Apps.

1. Search for failure reports with the CRTE - Created status set in the last seven days for plant 1100. Store the results in the collection FailureReports (and clear it if it already had some data)

ClearCollect(FailureReports, MaintenanceAPI.SearchFailureReports("recent-status-activations", "<my subscription key>",{'status-id':"CRTE",'plant-id': "1100", 'max-days-since-activation':7}))

2. Lookup the failure report with id from the failureReportId local variable

ClearCollect(FailureReportSelected, MaintenanceAPI.LookupFailureReport(failureReportId, "<my subscription key>",{'include-status-details': false,'include-tag-details': false}))

To understand the operations and its parameters available see this documentation.

The resource will be named according to common terminology used across the Oil&Gas industry (for example Norsok standard NS-EN 13306 and ISO 14224).

Example of resources are /work-orders/preventive-work-orders and /plants/{plant-id}/tags .

Resources keys will indicate the resource type as part of the name. Example: workCenterId and priorityId.

If there is a common "supertype resource", the supertype will determine the naming standard of the key. Example: FailureReports and ActivityReports are both a type of MaintenanceRecord. Therefore, the key for both is recordId.

Some resources may have multi-line text describing the resource or the contents of it in more detail. This will always have property name text.

All date and time information are based on UTC (Universal Time Coordinated) and formatted according to RFC3339. This also applies to durations, such as 1 day or 2 hours.

Example values:

• datetime: 2022-08-24T14:15:22Z
• date: 2019-08-24
• duration: P0Y0M1DT0H0M0S (one day) and P0Y0M0DT2H0M0S (two hours)

These values are easily compatible with libraries such as moment.js library.

It's worth mentioning that in some special cases for maintenance data outside of Norway, datetimes after timezone conversion is not what the end-users would expect. The reason for this is that users may have entered datetimes in their local timezone into the Equinor ERP system, but the Equinor ERP system is configured to treat the input as if it was in the current Norwegian timezone (UTC+1/UTC+2). This causes a disrepancy in the Equinor ERP system which can not be corrected for in Maintenance API. basicStartDateTime and basicEndDateTime for work orders are examples of properties which may have unexpected time conversion.

From some resources there will be a need to provide uri links to other endpoints. This can for example to provide the endpoint for download of a binary attachment from a work order resource it belongs to.

The link will be defined in the data model of the resource and be grouped under the property name _links. The name of the properties for the _links object will taken from Link relations defined through RFC8288 when possible. Typical link relation names are self and enclosure.

The uri will not include query parameters required or supported by the endpoint (such as api-version, include-operations etc). Subscription key header (Ocp-Apim-Subscription-Key) must also present in the subsequent request.

"attachments": [
{
    "attachmentId": "H4sIAAAAAAAACqsxMDA1MDVzNDQ3srAwdHVxdDR0dDI1MjB3MjFyMzA0cqsxMgAqMTExq6mpMTQwMDSwNKoBitQ4GRsA6ZqAzOSS0qLU-LTMvJTMvHQFXQXn_IJKBQ1jTb2CvHQAwLV5WV4AAAA",
    "fileName": "equipment_location.jpg",
    "fileSize": "1636352",
    "mimeType": "image/jpg",
    "_links": {
        "enclosure": "/work-orders/preventive-work-orders/20005446/attachments/H4sIAAAAAAAACqsxMDA1MDVzNDQ3srAwdHVxdDR0dDI1MjB3MjFyMzA0cqsxMgAqMTExq6mpMTQwMDSwNKoBitQ4GRsA6ZqAzOSS0qLU-LTMvJTMvHQFXQXn_IJKBQ1jTb2CvHQAwLV5WV4AAAA"
    }
}

Lookup operations return a single instance for the resource based on the key.

The resource may have related data which may or may not be relevant for a client. In order to indicate which related data to include, the lookup operation provides include-... query string boolean options. Examples: include-operations and include-tasks

Clients need to retrieve a subset of all resources for an endpoint. Usually, the criteria are non-trivial and in many case are not direct properties of the resource. REST does not provide a well-defined pattern for these types of requests.

Our approach, is to provide predefined filters with parameters. Each filter is documented in the OpenAPI specification.

Examples: maintenance-records/failure-reports/?api-version=v1&filter=recent-status-activation&status-id=RIDO&max-days-since-activation=1 and /maintenance-orders/preventive-work-order/?api-version=v1&filter=same-maintenance-plan&work-order-id=12345678&max=5

Update operations for resources will utilize a sub-set of the JSON Patch proposed standard. JSON Patch is described in RFC 6902 with a user-friendly version at http://jsonpatch.com/.

Our goals with using JSON Patch is to focus on the intent of the update and avoid common pitfalls for the client. The common pitfalls we avoid with JSON Patch are:

1. Clients inadvertently resetting properties of a resource to an empty value. This due to the client mistakenly sending all properties of a resource in a HTTP PATCH request with some of them having an initial value.
2. Clients inadvertently overwriting changes made by other users directly in the back-end system. This due to client mistakenly have provided properties which have not been changed in a HTTP PATCH request.

Using JSON Patch is straightforward.

• Set the content-type to application/json-patch+json.
• In the body, send an array of JSON Patch operations. Typically, one element pr property to be update for the resource

As part of the OpenAPI documentation, we will provide concrete examples for all update operation. In addition, the schema definiton for the request body defines which resource properties can be updated.

Example of JSON Patch request body which replaces the value of the properties title and text:

[
  {
    "op": "replace",
    "path": "/title",
    "value": "Material failure"
  },
  {
    "op": "replace",
    "path": "/text",
    "value": "OBSERVERT FEILTILSTAND FYLLES UT AV INNMELDER:\nBeskriv feilen så godt som mulig (legg gjerne med bilde):\nMaterial tretthet..\n"
  }
]

HTTP response codes will follow established best practice for REST services and will be documented in the OpenAPI specification.

Below is a list of status codes used in the API which the client should handle. Common:

• 400 Bad Request - The request is invalid. For example missing parameters in the query string
• 401 Unauthorized - The request did not include an authentication token or the authentication token was expired or invalid
• 403 Forbidden - User does not have sufficient permissions
• 405 Method not allowed - HTTP verb not supported for requested resource
• 500 Internal Server Error - Sorry, an unexpected error occured on our side. Let's us know and we'll get around to fix it
• 503 Service unavailable - API or a service it depends on is currently not available.

Read - HTTP GET:

• 200 OK - The request completed successfully
• 404 Not Found - The resource does not exist or an non-existing endpoint has been called

Create - HTTP POST:

• 201 Created - Create of resource was successful and resource is returned in body
• 400 Bad Request - The resource provided in the body is not according to specification
• 409 Conflict - The creation of this resource is in conflict with an already existing resources

Create - HTTP PUT

• HTTP PUT only used for file uploads
• 204 No Content - Request successful but no resource returned in body
• 400 Bad Request - HTTP Put failed due to file contents
• 413 Payload too large - File too large

Update - HTTP PATCH:

• 204 OK - Update of resource was successful and resource is returned in body
• 400 Bad Request - The resource properties to update is not according to specification
• 409 Conflict - The update of this resource is in conflict with an already existing resources

Delete - HTTP DELETE:

• 204 OK - Delete of resource was successful
• 404 Not Found - The resource does not exist or an non-existing endpoint has been called
• 409 Conflict - The delete of this resource is in conflict with an already existing resources

Endpoints that return multiple items will in some cases support pagination. This helps improve performance by only fetching the data which is necessary for the client.

Parameters page and per-page are used to define which page is fetched and how many records are returned in the current request. per-page will typically have a max limit defined in the endpoint's documentation.

The response of a pagination request will include 3 additional HTTP headers:

• Total-Count: Custom HTTP header which shows total number of items found matching the criteria of the request (not just in the page returned)
• Link: Pagination data in accordance to RFC 5988. This will include a link for the next, previous, first and last page.
• Link-Json: Custom HTTP header for making the information in Total-Count and Link accessible in an easy to read JSON format

Clients are recommended to use Link-Json HTTP header to traverse the pages. Example of the data in this HTTP header:

{
  "totalCount": 49,
  "links": {
      "next": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=3&api-version=v1",
      "prev": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=2&api-version=v1",
      "first": "https://api-test.gateway.equinor.com/maintenance-api/equipment?api-version=v1",
      "last": "https://api-test.gateway.equinor.com/maintenance-api/equipment?page=4&api-version=v1"
  }
}

Note: For some endpoints there is a risk that individual items "disappear" between pages if data is updated in ERP system whilst the pages are requested.

The Maintenance API will use the principles of API evolution instead of introducing a new api-version on every breaking change.

In order to achieve this, endpoints, query parameters and resource properties can become deprecated and will be marked so in the OpenAPI specification.

In general, depcrated properties will be removed after 3 months. If a client uses a deprecated endpoint or query parameter, the Maintenance API will in the response provide a Sunset HTTP header Sunset: Sat, 15 May 2021 12:59:59 GMT representing the removal date for the deprecated feature as specified in RFC8594. In addition, a HTTP header Link: <https://equinor.github.io/maintenance-api-docs/#section/Deprecation>; rel="sunset" will be provided to pointing to relevant documentation.

Clients must monitor these messages and take corrective actions.

Rename area to location

In order to align naming of structured locations within a plant across Equinor systems, Maintenance API is renaming areaId,area-id and area to locationId,location-id and location.

This deprecates the following endpoints:

1. /plants/{plant-id}/areas - Use new endpoint instead /plants/{plant-id}/locations

This deprecates query parameters for the following endpoints:

1. /work-orders
2. /work-orders/corrective-work-orders
3. /work-orders/preventive-work-orders

This deprecates HTTP POST request properties for the following endpoints:

1. /work-orders/corrective-work-orders
2. /work-orders/project-work-orders
3. /work-orders/sas-change-work-orders

This deprecates properties of the response in the following endpoints:

1. GET /plants/{plant-id}/tags/{tag-id}
2. GET /plants/{plant-id}/tags
3. GET /maintenance-records/failure-reports/{record-id}
4. GET /work-orders
5. GET /work-orders/corrective-work-orders/{work-order-id}
6. GET /work-orders/corrective-work-orders
7. GET /work-orders/preventive-work-orders/{work-order-id}
8. GET /work-orders/preventive-work-orders
9. GET /work-orders/sas-change-work-orders/{work-order-id}
10. GET /work-orders/sas-change-work-orders
11. POST /work-orders/sas-change-work-orders
12. GET /work-orders/project-work-orders/{work-order-id}
13. GET /work-orders/project-work-orders
14. POST /work-orders/project-work-orders

Rename quantityUnit to quantityUnitId

quantityUnitId is added to differentiate the field from future requirement where a description of quantityUnit might be added.

This deprecates the response in the following endpoints

1. GET /work-orders/corrective-work-orders/{work-order-id}
2. GET /work-orders/preventive-work-orders/{work-order-id}
3. GET /work-orders/sas-change-work-orders/{work-order-id}
4. GET /work-orders/project-work-orders/{work-order-id}
5. GET /work-orders/subsea-work-orders/{work-order-id}
6. GET /work-orders/modification-work-orders/{work-order-id}

Feature requests are welcomed and can be submitted through:

1. Github issue for maintenance-api-docs
2. Equinor Slack channel #maintenance-api
3. Contact in GBS IT PLA POM department

Endpoints have been introduced in the current version

Endpoints which have been modified in the current version