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 is planned to introduce system-to-system support in Q4 2020.

The solution will be based on the OAuth 2.0 client credentials flow.

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 setting up a system user in Equinor's ERP system and help define a role with only the necessary authorizations based on the client's usage scenario.

The following steps needs to be performed for the initial setup of a consumer application:

1. Create a client app registration in Equinor Azure AD through portal.azure.com for each environment of your solution
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
5. Trigger an authentication request through a http client (such as postman) in order to trigger the approval process of the API permission
6. Create a Github issue for maintenance-api-docs to establish contact with the Maintenance API team which would love to hear how you want to use the API and to allow us to map the subscription key to an application in our logging

We recommend using Postman as a tool for experimenting with the API and provide some example collections and environments to use

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, endoints, 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

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.