API Overview and Architecture

SOAP and RESTful APIs

The Brand Compliance APIs are web services in both SOAP and RESTful architectural styles. In general, the SOAP services are developed for specific requirements or are historical services. Unless there is a definite requirement for a SOAP implementation of a service, any new services or new versions of services are implemented using the RESTful architectural style.

Request and Response XML

In general, APIs exposed by Brand Compliance as web services use XML messages for both requests and responses. Exceptions to this are RESTful services where the use of an XML request is replaced by the use of URI parameters in a GET call. The APIs do not support other message formats, such as JSON.

The XML data schemas are written to allow for both forwards and backwards compatibility. All elements within the XML schemas are marked as optional. The element names are ordered so that new fields are added after existing elements and, within each sequence of elements, the last element is always an any element so that fields added in future versions are ignored by clients that are using an old version of the schema. For example:

<xs:complexType name="fpsMicroTestLocaleDataFullDTO">
    <xs:sequence>
        <xs:element form="qualified" minOccurs="0" name="description" type="xs:string"/>
        <xs:element form="qualified" minOccurs="0" name="locale" type="xs:string"/>
        <xs:element form="qualified" minOccurs="0" name="id" type="xs:long"/>
        <xs:element form="qualified" minOccurs="0" name="createdOn" type="xs:string"/>
        <xs:element form="qualified" minOccurs="0" name="updatedOn" type="xs:string"/>
        <xs:any maxOccurs="unbounded" minOccurs="0" namespace="##other" processContents="lax"/>
    </xs:sequence>
  </xs:complexType>

The element names in the XML Schemas are defined by the core system and do not change in specific implementations. If an implementation has additional fields that have been added to the system (the implementation is non-core), those fields may be exposed after the core fields (before the xs:any element) and will incur a maintenance overhead in later versions to cope with any additional core fields added after the custom fields.

Data types in the XML Schemas are the standard datatypes for XSDs, WSDLs, and WADLs. Values should be entered as described on the following web site:

http://www.w3.org/TR/xmlschema-2/

The following table lists the common data types used in the Brand Compliance schemas:

Data Types

Type	Example
xs:string	A normal string
xs:string	<![CDATA[A String with <br/> html data]]>
xs:long	9223372036854775807
xs:int	2147483647
xs:short	-32768
xs:boolean	true or false
xs:boolean	1 or 0
xs:date	2015-01-30
xs:dateTime	2015-01-30T23:59:59

Versioning

Due to the format of the XML schemas as described above, most revisions of the web services should be forwards and backwards compatible to allow clients of those web services to be upgraded and developed without binding the lifecycle of the client services to the upgrade cycle of Brand Compliance.

Where the necessary changes to a service cannot be made compatible with previous versions, a new endpoint will be created to expose the changed service. If possible, the previous version of the service will remain available at the original endpoint to enable existing and legacy clients to continue to work, but will be noted as deprecated in documentation to encourage developers of clients to the services to avoid using it.

Logging

All calls to APIs exposed as web services are logged within the application and can be viewed by logging into Brand Compliance as a Power User, navigating to Company > Admin> Notifications, and choosing the Web Service Log option. For each call, the name of the web service, date and time of the call, status (in progress/completed/failed), duration of the call (not available for In Progress calls), and a list of error messages if the call failed are shown.

The request and response XMLs are attached to each web service log entry. If a request does not contain XML, no attachment is created.

Accessing the APIs

This section describes how to access the APIs.

Availability

If enabled within the portal, an API is accessible while the portal is online. The support for a portal's availability is subject to the client's service level agreement.

Updates to the APIs are applied as per changes and fixes to the application. Each release involves a scheduled period of downtime. Details of the change and impact are covered in the supporting Release Notes.

Note:

After a Brand Compliance upgrade release, it may be necessary to change the URLs that the external system uses to call the APIs.

Deployment Model

The APIs, made available by Brand Compliance, are all web services implemented using either a SOAP or RESTful architecture.

The web services are exposed over HTTPS and require HTTP Basic authentication in order to access the service requested.

Authentication

In order to authenticate with Brand Compliance when accessing an API deployed as a web service, a user name and password must be supplied for HTTP basic authentication. Within Brand Compliance, the External System record controls access to the web services.

To see the list of existing External System records, log in to Brand Compliance as a Power User, navigate to Company > Admin > Roles and Permissions, and select the External Systems option.

To create a new External System:

Select the Actions > New action to open up a tab for creating an External System.
Enter a Login ID (User Name) and Email Address, then select the Actions > Save & Exit option.
An Oracle Identity Cloud Service (IDCS) or Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) profile will be automatically created and a notification email sent to the specified email address, containing instructions for setting the password.

The passwords used for External Systems are validated against the same criteria as the passwords for users of Brand Compliance. It is likely that a minimum length, mixed case, and digits will be required for the password, depending on the setup of the IDCS or OCI IAM tenant.

Note:

From 18.2, IDCS or OCI IAM is used to authenticate access to the services. Calling a service using a web browser does not generate the necessary header for IDCS or OCI IAM authentication, thus resulting in a 401 or 407 authorization error. Instead, a web service tool should be used.

A web service tool such as PostMan, SoapUI, or a lower-level tool such as curl or wget must be used in order to be able to send the authentication header for each request while using Basic authentication.

Authorization

At present, all APIs are available to all authenticated requesters.

Listing Available APIs

In all installations of Brand Compliance, a full list of the deployed web services can be found at /services.

For example, for a system where the application is deployed to URL https://www.example.com/brandCompliance, you can retrieve a list of all services from https://www.example.com/brandCompliance/services.

Note:

In order to access the /services page, the user must first be logged in/authenticated with the Brand Compliance portal.

When downloading the WSDL or WADL files, if prompted for further credentials, enter the Login ID and Password of the External System account.

To download the REST API WADL files:

Run the Windows Command Prompt app.
Enter the command curl [url]/services/rest/[api]?_wadl=true -u[login] > [api].wadl

Where [url] is the portal address; [api] is the name of the REST API; [login] is the login id of the External System account. For example:
```
curl https://<hostname>/services/rest/user?_wadl=true -uPROD_SYS > user.wadl
```
The file will be downloaded to your default directory. To download to a specific directory, provide the full path for the .wadl file. For example:
```
... -uPROD_SYS > c:\Users\JSmith\Downloads\APIs\18.2\user.wadl
```
Enter the password for the External System login id.

The file is saved to the specified location.
Import the WADL file into SoapUI.

Note:

If using SoapUI and the HTTP 401 error is received, click the Auth tab on the request in SoapUI and add Basic authorization. Also check the Authenticate pre-emptively option, then resubmit the request.

To download the WSDL files for SOAP APIs:

Run the Windows Command Prompt app.
Enter the command curl [url]/services/[api]?_wsdl -u[login] > [api].wsdl

Where [url] is the portal address; [api] is the name of the REST API; [login] is the login id of the External System account. For example:
```
curl https://<hostname>/services/activityManagement?wsdl -uPROD_SYS > activityManagement.wsdl
```
The file will be downloaded to your default directory. To download to a specific directory, provide the full path for the .wsdl file. For example:
```
... -uPROD_SYS > c:\Users\JSmith\Downloads\APIs\18.2\activityManagement.wsdl
```
Enter the password for the External System login id.

The file is saved to the specified location.

Note:

If using SoapUI and the HTTP 401 error is received, click the Auth tab on the request in SoapUI and add Basic authorization. Also check the Authenticate pre-emptively option, then resubmit the request.

REST API Path

A REST API Path system parameter allows for an alternative path to the REST APIs to be specified. This is of use where for example an alternative data center is being used, or where HTTP is being used instead of HTTPs.

By default, the path of the Base URL system parameter is used for the application and the APIs. The Rest API Path system parameter is only used if there is a need to override the base URL.

Change History

Change History Log

Each record contains a Change History log, which is maintained by the system as a result of the user creating or updating the record in the UI. The log is also maintained by the system if the record is created or updated using the API.

The log comprises:

Created On - the date and time the record was created.
Created By - the name and email address of the user who created the record (or ‘System’ if created by the API).

Changed On - the date and time the record was last updated.
Changed By - the name and email address of the user who last updated the record (or ‘System’ if updated by the API).

Field Change - a list of each time the record was updated:
- Changed On - the date and time of the update.
- Changed By - the name and email address of the user who made the update (or ‘System’ if updated by the API).
- No. Changed Fields - the number of fields that were changed by the update.
Opening an entry shows the details of the individual field changes:
- Field label
- From (before) value
- To (after) value

The log is not included in the API’s XML payload so cannot be retrieved or updated by the API.

Status Change History Log

Records that have a workflow status also have a Status Change History log - a table that has a row added by the system each time an update to the record results in a status change.

The table comprises the columns:

Status Before - the record’s status before the update.
Status After - the record’s status after the update.
Changed On - the date and time of the update.
Changed By - the name of the user who made the update (or ‘System’ if updated by the API).
Comments - any comments entered as part of the status change action.

The log is included in the API’s XML payload for retrieval, within the statusHistory element:

<statusHistory>
  <comments>
  <localeData>
    <locale>
    <statusFrom>
    <statusTo>
    <id>
  <id>
  <createdOn>
  <updatedOn>
  <statusChangedBy>
    <code>
    <disabled>
    <externalAuthenticationUser>
    <timeZone>
    <userType>
    <id>

For records with a Status Change History log, the APIs currently allow for rows to be added, removed, and updated in the table. Currently, the Product Record and Site APIs have the following additional controls, which in time will also be applied to the other APIs:

The update process is locked down to only allow the Comments column to be updated.
The Changed By column can be populated with a valid user’s name with the statusChangedBy element.

If no data is supplied for statusChangedBy, the Changed By field in the UI will default to ‘System’. In this case, the underlying value is null, so when retrieving that data using the API, the statusChangedBy element will be omitted (this is per the standard rule for omitting elements that have no value).

Security Considerations

This section provides information on aspects of security you need to consider.

Password Management

Unlike interactive logins for users, the use of web services does not permit warnings to be included in the returned messages. Also, there is no guarantee that there is someone handling the call in order to interpret any warnings about password expiry. Therefore, Brand Compliance does not currently apply the password lifetime rules to External Systems.

Note:

It is recommended that the passwords used for accessing APIs deployed as web services are changed regularly and that passwords are not reused or changed in such a way that the next value is predictable, such as, do not change from Password11 to Password12.

The passwords used to access the Brand Compliance APIs should be stored securely to prevent potential attackers from being able to masquerade as an authorized system.

Rich Text Data

In Brand Compliance, certain fields allow the display of HTML-formatted data. Such data is cleansed before display in Brand Compliance to ensure that any attempts at Cross-Site Scripting (XSS) attacks are mitigated, but this cleansing is not applied within the APIs. Therefore, it is advisable to cleanse any HTML-formatted data before it is displayed to users.

Excluded Fields

Many of the APIs published by Brand Compliance provide access to manage all of the records of a given type. With certain records, the fields accessible through the API are a subset of the fields within Brand Compliance. Any updates leave those fields unchanged.

Secured Connections

As all of the APIs are exposed as web services over HTTPS, it is necessary for callers to communicate over SSL/TLS using the ciphers that the Brand Compliance servers accept. To ensure optimal security, it is advised that standard certificate checks are in place and not disabled. In the case of Apache CXF, the Client TLS Parameter disableCNCheck should be left as false.

URL Encoding

Certain characters within URLs are reserved for a special meaning. In order to avoid calls that contain these characters being blocked by the API's security, the characters must be encoded and passed as plain text.

The reserved characters include ";", "/", "?", ":", "@", and "=", all of which could be present in the parameters passed to Brand Compliance APIs - such as within email addresses or within the names of users, products, or suppliers.

UTF-8 URL encoding should therefore be applied to all calls to the Brand Compliance APIs. The APIs will automatically decode the values on receipt.

For example, an un-encoded call of: …/services/rest/user/byKey/john.smith@example.com

should be encoded as: …/services/rest/user/byKey/john.smith%40example.com

The use of forward slash in parameters should be encoded as "%2f", for example an un-encoded call of: …/services/rest/user/byKey/24/7 Support

should be encoded as: …/services/rest/user/byKey/24%2f7 Support

If a call comprises multiple values, each must be encoded individually.

Reference Fields

This section describes how data is returned for fields that have their values derived by referencing a glossary or system text, such as the selections made from a configurable list of values.

Glossary and Locale/Language Fields

Fields that have their values selected from a glossary of configurable options generally have the code, description, and language translations of the selected value returned, along with the id reference to the glossary record.

The language translations are contained within a localeData element. Prior to release 18.0, a separate localeData element was returned for each language the portal had configured, now just the languages that the portal actually has active are returned. If a translation is not present for a language, the element is omitted, so if the portal has no alternative languages active, just a localeData element for the base language is returned.

Note:

Some APIs allow a locale parameter to be passed to optionally return a specific language, or languages. However, use of the parameter can have an impact on the call's response time, due to the additional selection processing.

Enumeration Fields

Certain reference fields have their options defined as system text rather than a configurable glossary. Referred to as enumerations, these are used where the selections are generally static, such as Yes/No options. Prior to release 18.0, just the code of an enumeration was returned, now the description of enumeration value is also returned as a description element.

Editable Text Selector Fields

Certain reference fields allow for a statement to be selected from a glossary and inline values entered after selection. Referred to as editable text selectors, these are used to build statements with variable content, but using a consistent format; for example, to describe cooking instructions in a common way without having to have an entry in the glossary for every permutation of time and temperature. Prior to release 18.0, just the separate statement and value elements were returned, now a packCopyText element containing the formed statement is also returned.

Key Features of the API Process

This section summarizes the key aspects of the API process:

The external system makes a call to Brand Compliance using HTTPS. The external system must be registered in Brand Compliance, and the user ID and password must match.
Calls to RESTful services use the GET, POST, PUT, and DELETE methods to retrieve, create, update, and delete records respectively. Calls to SOAP services use a predefined set of methods to perform the operations.
Each call is logged in the Web Service Log in Brand Compliance. The request and response XML messages are attached to the logs.
A predefined set of parameters is available to apply filters to the call, to retrieve a specific record or set of records.
Data is returned as XML, as defined by the associated WADL or WSDL schema. Only elements that contain data are returned; empty elements are omitted.
For RESTful APIs, an initial GET call to the service returns the unique internal key ID of the returned records in either the recordId or the id element. The record ID is then used in a subsequent call using a URI to retrieve the record's full XML data set, or to perform an update operation.

Update functions require the full set of fields and their values to be passed, as the full contents of the record are replaced. If all fields are not present in the external system, the update process would need to first retrieve the current contents of the record from Brand Compliance before applying the changes to that data set, and submitting the full data set as the update.
There could be several initiators for the data exchange, including the following:
- Human initiation, where an individual makes the request, such as by clicking a button to run the request.
- End user action, where the completion of an activity in the external system triggers the exchange.
- Scheduled request (or polling), where the external system sends or checks for data on a regular basis. For example, it may be looking for newly created Product Records or Specifications with a change in status.
For security purposes, the APIs rely on the external system polling, retrieving or submitting calls to the APIs. Brand Compliance does not push data externally.
The nature of the APIs may require multiple requests to be made, for example:
- Request a list of Product Records with their IDs.
- Request the timestamp reference for each Product Record.
- Identify any Product Records changed or created within a given time scale.
- Request the full details for that Product Record.

These types of requests can be automated. The external system is altered to enable the operations to take place in sequence according to a pre-defined algorithm.

Certain modifications can also be made to the external system to enable the storage of data returned from Brand Compliance. For example, if the external system requests a record to be created in Brand Compliance, a confirmation response is sent, containing the record ID. This ID may then be stored in the external system for future reference.

Note:

An External System must be specifically granted access to an API, either by the service or its endpoints. If none are specified, the External System will not have access to any of the APIs.

If a service is selected, it grants access to all of its endpoints, so there is no need to select the individual endpoints (if access is required to all of them); but selecting the service and all its endpoints would have the same effect.

Endpoints can be selected individually to grant granular access to specific endpoints of a service. In this case it appears that if the service is also selected, that overrides the endpoint selections, thus providing access to them all anyway. So if wanting to grant access to just specific endpoints, the way to do it is not to select the service, but just the individual endpoints.