Who is this article for?

Enterprise or Decani users searching records that meet various criteria and help populate data repositories.

Interface development role is required. It is a read-only HTTP/JSON API.

Search API is a publicly accessible HTTP/JSON API designed to facilitate robust read-only search capabilities. This API facilitates the collection of large volumes of data, allowing businesses to perform detailed analysis and gain deeper insights into their operations.

It must be coordinated through your organisation's Customer Support Administrator and Account Manager.

This article explains all the steps you need to take to be able to use the Search API effectively.

1. Overview

One of the prevalent applications of Search API is in the realm of data warehousing, where it serves as a vital resource for populating data repositories. Established repositories can be leveraged in conjunction with third-party reporting tools, based on the data retrieved through the API. 

Search API differs from RESTConnect in a couple of ways:

• RESTConnect is a Create/Read/Update/Delete (CRUD) API designed to perform actions against single objects.
• Search API is a query API designed to execute queries and return search results. It's a read-only API that interfaces directly with the platform search database. No module rules (DXL) are run when using Search API.

2. Prerequisites

Before executing a search using the Search API, several preparatory steps must be taken to ensure proper functionality and security.

Make sure that:

• Module Package Cache feature is enabled. We can let you know if this has been enabled, and if it hasn't, what steps need to be taken to enable it.
• You have a valid user account. The user account used to authenticate will be limited to the same objects it has access to in the desktop interface.
• Defined global, system, and custom common fields are always searchable and provide consistent data across modules.
• Search API supports various conditions, including compound and simple ones like EQUALS, BETWEEN, and TODAY.
• Set query conditions to help refine the search criteria, allowing users to filter and retrieve specific facats data  and stat objects effectively.

Properly setting these conditions is essential to accurately and securely execute a relevant search result.

3. Security

To ensure secure, personalised API interactions, each authenticated request requires a valid session to access the user's specific context.

Un-authenticated requests can be made to:

• /api/auth?subscriber={QUHKTT3671}
  Create new session from username+password or OAUTH token

Authenticated requests:

• /api/v1/search
  REST API for retrieving object search data in a read only manner.

4. IP whitelisting

Only transactions from authorised IP addresses will be recognised.

Please register the development (DVT), testing (UAT), and production (Prod) environment IP addresses with our Operations team. IP address ranges are supported.

5. Authentication

Only authenticated active users can execute a search API. The authentication routes provide ways to authenticate and create an active session for searching. Most use cases will use DWAYSessionId created from other API calls.

5.1. Basic authentication

• HTTP Request Type: POST
• HTTP Path:  /api/auth

Headers

• Authorization: Basic YWxhZGRpbjpvcGVuIHNlc2FtZQ==
• Authorization: Bearer QSBzZWNyZXQgdG9rZW4= A system generated Bearer token
• Accept: application/json
• Content-Type: application/x-www-form-urlencoded

Request body

• Request body is in the form of form parameters. The only parameter is subscriber = RPVJG13552.

Response body

• Response body will contain meta-data about the user.

{
    "firstName": "Frank",
    "lastName": "Smith",
    "email": "fsmith@devonway.com",
    "userName": "fsmith",
    "lastLoginDate": "2019-07-08T22:02Z",
    "subscriberCode": "subscriber_code",
    "modules": [
        "moduleA",
        "moduleB",
        "moduleC",
        "moduleD",
        "moduleE"
    ],
    "teams": [
        "Workflow Basic",
        "Corporate Level 1 Approver",
        "Electrical A",
        "Holding Tank"
    ],
    "languageCode": "AMENG",
    "logTag": "subscriber_code-190708160705955X00011178935100",
    "customDateFormat": "",
    "timeZoneCode": "EST"
}

5.2. OAUTH2 authentication

Only users with the Interface (OAUTH) user type are allowed to perform OAUTH2 authentication, while users without this user type will be denied permission.

• User Type (1): Interface (OAUTH)
• Login Behavior (2): Allow Username/Password

To perform OAUTH2 authentication, two calls are needed to create a session.

The first call uses basic authentication to retrieve an access token, and the second call utilises this access token to perform an OAUTH2 authentication to create a session.

• HTTP Request Type: POST
• HTTP Path: /APIServices/oauth/authorize

Headers

• Authorization: Basic YWxhZGRpbjpvcGVuIHNlc2FtZQ==
• Accept: */*
• Content-Type: application/x-www-form-urlencoded

Request body

• Response body is in the form of form key values and requires four key values to be set. The first one being subscriber = RPVJG13552 and the second one being grant_type = client_credentials.
• Users of types other than Interface (OAuth) will not be able to use the new client_credentials grant type.
• Third and fourth key values would be client_id, and client_secret with the expectation that the value for client_id would be the username and client_secret would be the password of the user account of type Interface (OAuth).

Response body

• Response body will contain meta-data about the user.

{
  "access_token": "askbo3294hdbflkswyHJVRL347asHnek==",
  "expires_in": "31536000"
]