Web Service

The following steps outline the process of configuring a new Web Service:

1. From the Table of Contents, expand Administrator and select External Access.
2. Expand External Access and select Web Services.

The Web Services TOC appears.



3. Click Create New Web Service.
4. The Web Service form appears.



5. Enter the required value in the Title, Endpoint Name, and Description fields.



Warning
The Endpoint Name property is used in the Web Service’s URL. This string may include alphanumeric characters and underscores. Do not use spaces or other special characters.
6. Click Done to save the changes.

The newly created Web Service form appears:

An Endpoint describes the scope of data, actions, and custom logic allowed for a Web Service. A Web Service must have at least one active Endpoint to “publish” a REST API. A Web Service may also have multiple Endpoints, each with a version number and unique URL. This capability enables users to make significant changes to an API without breaking existing client applications or integrations.

The following steps outline the process to create a new Endpoint:

1. Open the Web Service.
2. Click Edit.



3. Click Create New Version in the Endpoints section.



A row will be added to the Endpoints grid.



4. Click Save.

The Version and the endpoint URL will be updated automatically. Each endpoint has a unique URL with the following format:

{Innovator_url}/Server/ws/{endpoint_name}/v{endpoint_version}



5. Select the Endpoint.
6. Click Configure Endpoint.



The Web Service Editor opens.

The Web Service Editor consists of the following sections:

• The pane on the left enables the user to view and modify the Web Service Items (ItemTypes) and Global Methods included in the endpoint’s scope.
• The pane on the right enables the user to view and modify settings for any Web Service Item or Global Method selected in the left pane.

The following steps outline the process to add an ItemType to an Endpoint:

1. Click Edit in the Web Service Editor.





2. Click Add ItemTypes.

The Select Items dialog box appears.



3. Click Search.

A list of all the ItemTypes displays.



4. Select the required ItemType(s) and click OK.

The selected ItemType(s) will be added to the Web Service Items list.



Web Service Items may be removed from the Endpoint by selecting the item in the left pane and clicking the Delete button in the header of the right pane. Removing a Web Service Item from an Endpoint does not delete the ItemType from the database.

The following steps outline the process to configure a Web Service Item.

1. Click on a Web Service Item in the left pane.

The right pane will display settings for the Web Service Item in four tabs:

Web Service Item: Default tab displayed when a Web Service Item is selected Properties: Web Service Item’s properties that are available via the Endpoint Relationships: Web Service Item’s relationships that are available via the Endpoint Methods: Server Methods that can be run on the Web Service Item via the Endpoint

1. (Optional) Enter an Alias.

This string defines the name of the entity type representing the associated ItemType in the published API. The default value will be the name of the selected ItemType, and all spaces will be replaced with underscores.

Warning
Because Alias is used as the entity type in REST API calls, it must be unique and cannot contain spaces or special characters.
2. Select the Actions permitted for this Web Service Item. Get: Request item by id.

Get List: Request item(s) without the id parameter. Requires Get to be selected.Add: Create a new item.Edit: Edit an item.Delete: Delete an item.

The Properties tab displays a table of properties included in the scope of the selected Web Service Item. The column definitions are as follows: Property: Displays the name of the property Data Type: Displays the property’s data type as defined on the ItemType Property Data Source: Displays the property’s data source as defined on the ItemType Web Service Data Source: For properties with the “Item” data type, this field identifies a Web Service Item associated with the property’s Property Data Source. If the Endpoint has no corresponding Web Service Item, one will be created automatically.

The following steps outline the process to select properties for the Web Service Item:

1. Click the Properties tab in the right pane.
2. Click Add in the Properties tab.



The Select Properties dialog opens.



3. Select one or more properties.



4. Click OK.

The newly added properties will be displayed as shown below:



Properties may be removed from the Web Service Item by selecting one or more properties and clicking the delete button directly above the table. Removing a property from a Web Service Item does not affect the ItemType definition.

The Relationships tab displays the Relationship Types included in the scope of the selected Web Service Item. The column definitions are as follows:

1. RelationshipAlias: Name of the RelationshipType
2. RelatedAlias: Identifies a Web Service Item associated with the relationship’s ItemType. If the Endpoint has no corresponding Web Service Item, one will be created automatically.
1. Click the Relationships tab.
2. Click Add in the Relationships tab.



The Add Relationships dialog appears. It lists the Relationships for the Web Service Item’s associated ItemType and the related ItemType.



Select one or more Relationships.



3. Click OK.

The newly added relationships will be displayed in the table.



Relationships may be removed from the Web Service Item by selecting one or more rows and clicking the delete button directly above the table. Removing a relationship from a Web Service Item does not affect the ItemType definition.

The Methods tab displays the item methods, or “bound methods”, included in the scope of the selected Web Service Item. These should be server Methods explicitly developed for a context item of this ItemType.

The column definitions are as follows:

1. Alias: The name used to execute the Method via the Endpoint
2. Method: The server Method that will be executed
Warning
Because the Method Alias will be used in REST API calls, it must be unique and cannot contain spaces or special characters.

The following steps outline the process of adding Methods:

1. Click the Methods tab.
2. Click Add in the Methods tab.

The Select Item dialog appears.

Click Run Search.



A list of items will be displayed.

3. Select one or more items.



4. Click OK.

The newly added records will be displayed.



Methods may be removed from the Web Service Item by selecting one or more rows and clicking the delete button directly above the table. Removing a Method from a Web Service Item does not delete the Method from the database or affect the ItemType definition.

Global Methods, or “unbound methods”, are server Methods that can be executed independently of a specific context item type.

The column definitions are as follows:

1. Alias: The name used to execute the Method via the Endpoint
2. Method: The server Method that will be executed
Warning
Because the Method Alias will be used in REST API calls, it must be unique and cannot contain spaces or special characters.

The following steps outline the process to add Global Methods:

1. Click AddGlobalMethods directly above the left pane.

The Select Item dialog appears.

Click Run Search.



2. Click Search.

A list of all the corresponding Items will be displayed.



Select one or more server Methods.



3. Click OK.

The newly added method(s) are in the left pane.



4. Click a GlobalMethod in the left pane.

The right pane will display the Global Method’s settings in a single tab.

3. Alias: The name used to execute the Method via the Endpoint
4. Method: The server Method that will be executed
5. Parameters: This table enables admins to define named parameters that may be passed in the body of a request for use in the server Method code
Warning
Because the Method Alias will be used in REST API calls, it must be unique and cannot contain spaces or special characters.

Global Methods may be removed from the Endpoint by selecting the Method in the left pane and clicking the Delete button in the header of the right pane. Removing a Global Method from an Endpoint does not delete the Method from the database.

1. Click Done to save the Endpoint.

The following steps outline the process to create a new Endpoint:

1. Open the Web Service.
2. Click Edit.



3. Select the Endpoint by clicking on it.
4. Click Configure Endpoint.



The Endpoint opens in the Web Service Editor.



5. Click Edit in the Web Service Editor.
6. Edit the Endpoint as needed, following the appropriate steps from Sections 3.1.1.1 “Adding ItemTypes” and 3.1.1.2 “Configuring a Web Service Item”.
7. ClickDone in the Web Service Editor when all edits are complete.

Creating an Endpoint does not automatically make the REST API accessible. It must be published or made “active” before it can respond to requests. The following steps outline the process for publishing an Endpoint. Open the Web Service. Click Edit. In the Endpoints grid, enable the Active checkbox for the Endpoint to be published.

Click Done in the Web Service toolbar. The Endpoint is now published and can respond to HTTP requests. The Endpoint can be unpublished again by disabling the Active checkbox.

A Web Service may have multiple Endpoints, each describing a version of the Web Service. This enables the user to make significant changes to an API without breaking existing client applications or integrations. The following steps outline the process of versioning a Web Service with a new Endpoint. Open the Web Service. Click Edit. In the Endpoints grid, select the Endpoint that will be the basis of the new version. Click the Create New Version button in the grid toolbar.

Click Save in the Web Service toolbar. In the Endpoints grid, select the Endpoint with the new version. Click Configure Endpoint in the grid toolbar.

Edit the Endpoint as needed. Then Save the Web Service and publish the newest Endpoint version.

An API Key enables the Aras Innovator server to authorize requests and execute the request as the User associated with the key. API Keys are most commonly assigned to a service User that is used for server-to-server requests or other scenarios where an end user cannot be prompted for credentials.

API Keys contain the following properties: Name: Name of the API Key

User: The User that will be used for all requests made with this key. If a user is not entered, a system user will be automatically generated.

Description: Description of the API Key Created By: The User who created the API key Created On: When the API key was created

The following outlines creating an API Key for a Web Service.

1. Open the Web Service.
2. Click Edit.

Click the API Keys tab.



3. Click the New API Key button.

A new record will be added to the table, as shown below:



4. Enter Name.
5. (Optional) Enter the User that will be used for all requests made with this API Key.
6. If a User is not selected, one will be generated. If using a generated user, be sure to grant that user permission for the requests that will be made with the API Key.
7. Click Save.

Saving the record will display the API key. Save the key, as it will not be visible after creation.



8. Click Done.

The newly added API key will be displayed.

The Configurable Web Service produces REST APIs that follow the same OData protocol used by the platform’s default REST API. As a result, sending requests and receiving responses from a CWS Endpoint is very similar to the default REST API. This section will outline steps that are unique to using a CWS Endpoint and provide references to the RESTful API documentation for steps shared with the default API.

Each Aras Innovator instance has one endpoint for the default REST API. This default endpoint URL uses the following format:

{Innovator_url}/Server/odata/{…}

However, CWS can produce multiple REST APIs – each with a unique endpoint URL in the following format:

{Innovator_url}/Server/ws/{endpoint_name}/v{endpoint_version}/{…}

To confirm the Endpoint URL(s) for a REST API published via CWS, open the Web Service item and check the Endpoints tab.

All requests sent to the Aras Innovator server must be properly authorized. For the platform’s default REST API, that means an application must request an access token from the OAuth server and include it in the headers of each HTTP request. CWS supports both OAuth access tokens and API Keys. The following sections outline how to use each authorization approach in a request to a CWS Endpoint.

The process for using an OAuth access token with a CWS Endpoint is the same as the process for the default REST API.

The following steps outline the process of using an API Key to authorize a request to a CWS Endpoint.

Download the Postman application on the local machine. Under My Workspace, select Collections and click Create New Collection. Provide a name for the new Workspace. For example, “CWS Collection”.

Click Add a request under the new Collection.

Provide a name for the new Request. For example, “Metadata”. In the address bar, enter the CWS Endpoint URL.

Click the Auth tab.

Select API Key from the Type dropdown.

In the Value field, enter “apikey ” followed by an API Key generated with the steps in section Creating an API Key.

Click Send. The request should return a 200 OK response and the response body will appear in the bottom pane of the Postman application.

REST APIs published with CWS have a special metadata endpoint that describes the API’s schema in an Odata-compliant format. This schema can be accessed with the Endpoint url as shown in the previous section. It can also be accessed by appending #metadata to the Endpoint url.

The scope of the platform’s default REST API includes all ItemTypes and server Methods in the Aras Innovator database. This contrasts with the scope of CWS-published APIs, which include only the data and logic described in the Endpoint configuration. For example, CWS Endpoint that permits “get all” for Documents will respond with a 200 OK status and Document data in the response body.

However, the same CWS Endpoint will respond with a 400 Bad Request status if it receives a request for an ItemType that is not included in the scope.