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. Click button below to import the Maintenance API collection for Postman.

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 authorization in Equinor's ERP system. This is handled by the following roles which can be applied to from the internal AccessIT solution:

• YT105 - OM Mobile Apps & API (SAPP03)
• YT105 - OM Mobile Apps & API (SAPP05)
• General Operation & Maintenance roles based on the business role of the user

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.SearchFailureReport("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, which are encoded as P0Y0M1DT0H0M0S and P0Y0M0DT2H0M0S.

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

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:

• 200 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:

• Currently, no endpoints using HTTP DELETE

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

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 which are introduces in the current version

Endpoints which have been modified in the current version

Endpoints related to tag or equipment master data.

Provide master data for a plant for example for tags, areas and work centers. This is information is often required as parameters to other endpoints for example when creating a failure report.

Used to report work performed for a maintenance activity against a tag

Used when an equipment fault/degradation is detected or when there is need for work that is not related to equipment fault.