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.
   The Web Service form appears.
   

   

   

4. 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.
5. The OAuth Token Required Scope property defines the scope(s) that must be present when authorizing a request to this web service using an OAuth Client. This setting is optional. The default value is “Innovator.”
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 lets the user view and modify the Web Service Items (ItemTypes) and Global Methods included in the endpoint’s scope.
   • The right pane 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:
   
   1. Web Service Item: Default tab displayed when a Web Service Item is selected
   2. Properties: Web Service Item’s properties that are available via the Endpoint
   3. Relationships: Web Service Item’s relationships that are available via the Endpoint
   4. Methods: Server Methods that can be run on the Web Service Item via the Endpoint

Web Service Item

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.
   
   

   • 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.
   Note

   Configurable Web Service obeys all access controls configured on the Aras Innovator server. The Action settings for Web Service Items allow admins to permit or restrict certain operations for an Endpoint. Enabling an Action on a Web Service Item does not grant additional permissions.

   Properties

   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. One will be created automatically if the Endpoint has no corresponding Web Service Item.
   Note

   The id property is required for all Web Service Items and cannot be removed from the table.

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

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

   

   

   The Select Properties dialog appears.
   

   

   

4. Select one or more properties.
   

   

   

5. 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.

Relationships

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

• Relationship Alias: Name of the RelationshipType
• Related Alias: Identifies a Web Service Item associated with the relationship’s ItemType. One will be created automatically if the Endpoint has no corresponding Web Service Item.
  
  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.

Methods

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:

• Alias: The name used to execute the Method via the Endpoint
• 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:

• Alias: The name used to execute the Method via the Endpoint
• Method: The server Method that will be executed

The following steps outline the process to add Global Methods:

1. Click Add Global Methods 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.
   

   

   

3. Select one or more server Methods
   

   

   

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

   

   

5. Click a Global Method in the left pane.
   The right pane will display the Global Method’s settings in a single tab.
   
   • Alias: The name used to execute the Method via the Endpoint
   • Method: The server Method that will be executed
   • 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.

6. 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 “Adding ItemTypes” and “Configuring a Web Service Item”.
7. Click Done 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.

1. Open the Web Service.
2. Click Edit.
3. In the Endpoints grid, enable the Active checkbox for the Endpoint to be published.
   

   

   

4. 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.