API Developer Guides Overall
API Developer Guides Overall
Overview
The Empower REST API (Application Programming Interface) allows you to programmatically exchange data with your workspaces. This documentation includes details about requests and responses from Empower servers, and instructs developers in how to construct requests. This documentation assumes some familiarity with APIs in general.
API Format
The Empower API is based on a REST architecture and transfers JSON content exclusively (except for file content operations, which are JSON and multipart/form-data.)
The base URL is https://<the Root URL of your Empower Installation>/restapi.
For example, a request to return all Items in a workspace would be
https://<the Root URL of your Empower Installation>/restapi/items
The user constructs JSON requests to specific URL endpoints on the Empower API service. The API service responds with data, in the case of a GET request, or updates Empower objects in the case of a POST request. You can also perform PUT requests to specific URLs.
This document includes details about requests and responses from Empower servers, and instructs developers in how to construct requests. This document assumes some familiarity with APIs in general.
A Note on JSON inputs: When constructing Requests to the API service, please follow best practices for JSON data types:
Text values should be in quotes ("text")
Numeric values should not be in quotes (42)
Internal quotes in values should be escaped with the \ character (18").
Dates: All search values in Empower API are strings and should match the value as it appears within the Empower database.
GUID values should be in quotes ("2K4N1Y24FWFN6LDUC67B")
Each Empower object is represented by a GUID (Globally Unique IDentifier). When you perform a GET, you receive object GUIDs in return, and use those GUIDs to specify objects on which you perform actions.
So, you might perform a GET to determine the GUID of a particular Item, and then perform a PUT specifying that Item’s GUID to update its specification data.
Empower’s approach to a REST API distinguishes between two types of entities: an object itself (such as an item or file) and the relationship between two objects (such as a BOM line or file association.) This approach allows users to specify attributes both for the object and for the relationship.
For example, the attributes of an item might include, name, number, etc—but when that item is being added to a BOM, you need to specify attributes about the relationship between the item and its parent (which might include quantity, reference designators, etc.)
For URL Search attributes, all Data and Time requests are in strings and should match the date format as it appears within the Empower Database Search.
For Responses, Date and Time formats in the Empower REST API are in the following format: "2021-09-09 17:30:00” yyyy-MM-dd HH-mm-ss (yyyy is 4 digit year, MM is two digit month, dd is two digit day, HH is 2 digit 24 hr hour, mm is 2 digit minute, ss is 2 digit second).
Connecting and Permissions
An Empower API license for your Empower instance is required to use Empower API. Connect to the Empower API service by providing your Empower login credentials (username and password or username and access key) in a Log In request. The API service returns an access token which must be included in the header of all subsequent requests for the session. A session will timeout 24 hours after the last action and the token will thereafter be invalid.
Recommended best practices for connecting to the Empower API:
Use a dedicated user to access the Empower API. And more broadly, use a dedicated user for each integration connected to your Empower desktop.
Log in to the API, perform whatever actions you desire, then log out of the API when you are done.
API Requests
The Empower REST API provides methods for accessing a resource, such as an Item or a category of Item, at a canonical URL. You can then perform an action upon that resource by specifying an endpoint URL, such as
https://<the Root URL of your Empower Installation>/restapi//items/<item_GUID>/revisions
which returns all revisions for a given Item resource.
The header of all requests must include:
an Authorization declaration for user authentication (except Log In, which grants a token)
a content type declaration ("application/json", except for file POST endpoints with content, where the file metadata is JSON and the file payload itself is "multipart/form-data")
an HTTP method declaration (GET, POST, PUT, DELETE)
Requests must be sent uncompressed. Responses may be returned uncompressed or compressed using gzip encoding.
Your Empower may have a daily limit on API calls. Any attempt to make additional calls past the API Limit results in an error message.
The POST Log In and POST Log Out calls are exempt from the call limit rule.
The following response header information can be used to track the remaining number of calls for the day if your Empower instance has a daily call limit.
For the POST Log In and PST Log Out endpoints, the response headers will not be included.
| New Response Headers When API Limit is Enabled | Description |
|---|---|
| X-Empower-Requests-Remaining | Indicates the number of remaining calls that can be made for the rest of the day. |
| X-Empower-Request-Limit | Indicates the total number of requests that can be made in a 24 hour time period. |
| X-Empower-Next-Request-Limit-Reset | Indicates the time the number of calls reset to the maximum daily call limit. |
Responses
For calls that return responses (and not arbitrary binary data), responses will look roughly like:
{
"<object_field>":"<field_value>"
…
}
When the request returns multiple objects, responses look generally like:
{
"Count": 20,
"Results": [
{
"<object_field>":"<field_value>"
},
…
]
}
When a request returns one or more errors:
{
"Errors": [
{
"Code": <error_code>,
"message": "<error_message>"
}
],
}
To make responses more human-readable, the first level shows all core attributes. Second-level objects are shown in a compact version. In the Get Item BOM response example shown below, the second-level objects "Item" and includes only the "Guid".
{
"Count": 16,
"Results": [
{
"Guid": "185V00009G0000004",
"Item": {
"Guid": "100000000F00000JT"
},
"ItemNumber": 1,
"Qty": "1",
"UOM": "ea",
"FindNumber": "1",
"Refdes": "LB1",
"Alternates": "",
"Notes": "",
"Special": "",
"CustomFields": [
{
"Name": "Scrap Percentage (%)",
"Value": ""
},
{
"Name": "ERP Flag",
"Value": ""
},
{
"Name": "Dock Date",
"Value": ""
},
{
"Name": "Manufacturing Origin",
"Value": ""
},
{
"Name": "BOM Notes",
"Value": ""
}
]
},
...
]
}
Successes and Errors
As much as possible, Empower attempts to use appropriate HTTP status codes to indicate the general class of problem, and this status code is repeated in the response. The following two tables give supported success status codes and their meanings, and supported error status codes and their meanings.
| Success Code | Meaning |
|---|---|
| 200 OK | default success message |
| 201 Created | success and new entity created |
| Error Code | Meaning |
|---|---|
| 400 Bad request | returned if there is a syntax error in the request |
| 401 Unauthorized | returned if the requests require valid access token, but no valid access token is specified in http headers also returned if the login fails due to incorrect username or password or if due to timeout. |
| 403 Resource not found | returned if the user doesn't have the permission to acess the requested data or perform the requested operation. |
| 404 Resource not found | returned if the endpoint of a request is not supported or if the requested resource does not exist. |
| 415 Unsupported media type | returned if the content-type within the body is not application/json. |
API Sample Code
You can download a set of API sample requests, along with instructions for installation, from the Downloads page in Empower.