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.

To avoid sending the credentials on each request, the use of OAuth 2 / OpenID Connect is suggested; establish identity with IDCS or OCI IAM to get back an access bearer token and then supply that token on each request to the application's web services.

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

Updates made to Brand Compliance records through the APIs are shown in the record's Change History log with user shown as System. The Change History log data is not included in the XML payload.

Status Change History Log

For records that are subject to workflow, their Status Change History data is included in the XML payload, as follows:

Each row in the record’s Status Change History table is represented by a statusHistory element. It is populated accordingly when data is retrieved.
When a new record is created, a row can be added to the Status Change History table by populating the contents of the statusHistory element.
When updating a record, the only column of the Status Change History table that may be changed by populating the statusHistory element is the Comments column.
It is not possible to remove rows from the Change History table.
Status Changed By can be omitted if required, in which case within the application, the Status Change History table will display the system text value System in place of a user name. Or, Status Change By can be populated with a valid user (standard validation applies).
The contents of the statusHistory element are as follows:
```
<statusHistory>
  <comments>
  <localeData>
    <locale>
    <statusFrom>
    <statusTo>
    <id>
  <id>
  <createdOn>
  <updatedOn>
  <statusChangedBy>
    <code>
    <disabled>
    <externalAuthenticationUser>
    <timeZone>
    <userType>
    <id>
```
createdOn and updatedOn are set by the application when the record is created or modified.

statusChangedBy can only be set when the record is created, and can either be:
- omitted, to denote the System was responsible, or,
- a simpleUserDTO structure, whereby the child tag of <id> or <code> is used to specify the relevant user.
comments can optionally be specified during creation or update. If not specified, the application will show a dash.

localeData can be specified during creation only.

Where values are submitted but not permitted to update the status change history, they will be ignored.

See the Product Record page in the Oracle Retail Brand Compliance Management Cloud Service Data Dictionary, Volume 3 - Product data dictionary for details of the contents of the Change History tables.

Note:

The defaulting of System in place of a user name within the application does apply to all records with a Status Change History table.

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.