The CloudSpark API provides proxy endpoints for calling custom client API endpoints (Disco endpoints that begin with /Command/ClientAPI). There are proxy endpoints for:

• Authenticated customers
• Admin users
• Unauthenticated customers

Authenticated Customers

Authenticated customer accounts have proxy endpoints they can use:

• Simple /ProxySimple/
• Standard /Proxy/

These endpoints are called by custom content pages and widgets in the Web Office and eCommerce Shop.

ProxySimple and Proxy behave differently. You can get rid of that "Status" ID and any other structures and just work directly with results if you use Simple.

authenticatedAssociateId Parameter

It's unnecessary to pass an authenticatedAssociateId parameter on the POST to the proxy. The proxy will add this parameter automatically when it prepares to call Disco. Any call to the proxy that includes this parameter will be overwritten by the API proxy that contains the logged-in user ID. If a custom API doesn't need this parameter, it's ignored.

{ 
   associateId: 4567, 
   authenticatedAssociateId: 1234 
}

Custom API endpoints should use the authenticatedAssociateId parameter when they need the logged-in user ID. In the case of the preceding example, the API should check that the associateId passed is in the downline of the authenticatedAssociateId or perform whatever other security checks are prudent for the endpoint. If the API ignores this parameter, then it leaves a security hole open so that calls to this endpoint can be made through the proxy from any logged-in user.

Root Level Path /Command/ClientAPI

All custom client API endpoints begin with the root level path /Command/ClientAPI.

You don't need to include /Command/ClientAPI with your proxy call, as it is automatically prepended to the passed path. If you do include it, it will send as /Command/ClientAPI/Command/ClientAPI.

Request Timeout

Requests timeout after 10 seconds. If you need to adjust that timeout, an optional timeout query parameter, timeout, may be passed. The value is the number of seconds needed.

For example, Admin/Proxy/API/Integrations/ExampleReport?timeout=30

Simple Endpoint /ProxySimple/

The Simple endpoint is recommended over the Standard endpoint because the requirements are less strict for the custom API called. This endpoint uses the prefix /ProxySimple/ in the API call. Let's walk through what happens when a call is made to the Simple endpoint.

1. POST to the Simple API Endpoint

• Request URL: https://api.directscale.com/ProxySimple/Associates/GetEyeColor

• Request Body:

  JSON

  { 
     associateId: 4567 
  }
  

You must use a POST for the proxy endpoint request, even if you're not sending a request body to the proxy endpoint.

⚠Important

The logged-in customer account authentication token is required in the request header in the same manner as all other custom API endpoints.

2. The API Proxy Sends a Request to Disco

• Request URL: https://{clientname}.corpadmin.directscale.com/Command/ClientAPI/Associates/GetEyeColor

• Request Body:

  JSON

  { 
     associateId: 4567, 
     authenticatedAssociateId: 1234 
  }
  

For the proxy API to determine the correct clientname (Client ID) to use for the Disco request domain, it looks at the passed user authenticated token. Embedded in this token is the client to whom the user belongs.

3. Disco Returns a Message Back to the Proxy

• Response Status Code: 200

• Response Body:

  JSON

  { 
     Color: 'Green' 
  }
  

4. The Proxy Returns Data from Disco

• Response Body: { ResponseBody: { Color : 'Green' }, ResponseStatus: 200 }

The ResponseStatus is set to whatever HTTP response status code the call to the endpoint returned. The ResponseBody is set to whatever response body the endpoint returned. If the call to the Disco API timed out or had a TCP error, the proxy will return a 500 HTTP response with an empty response body.

Standard Endpoint /Proxy/

The Standard endpoint is the first version of the proxy. It expects endpoint responses in a certain format. This endpoint uses the prefix /Proxy/ in the API call. Let's walk through what happens when a call is made to the Standard endpoint.

Much of the info about the Simple endpoint applies here too unless otherwise noted.

1. POST to the Standard API endpoint

• Request URL: https://api.directscale.com/Proxy/Associates/GetEyeColor

• Request Body:

  JSON

  { 
    associateId: 4567 
  }
  

2. The API Proxy Sends a Request to Disco

• Request URL: https://{clientname}.corpadmin.directscale.com/Command/ClientAPI/Associates/GetEyeColor

• Request Body:

  JSON

  { 
    associateId: 4567, 
    authenticatedAssociateId: 1234 
  }
  

3. Disco Returns a Message Back to the Proxy

• Response Status Code: 200
• Response Body: { Status: 0, Message: null, Data: { Color: 'Green' } }

The API proxy is expecting the endpoint to return a JSON object in the response body with the properties:

• Status
• Data
• Message

4. The Proxy Returns Data from Disco

• Response Body:

  JSON

  { 
     ErrorMessage: null, 
     Response: { Color: 'Green' } 
  }
  

The response JSON object of the API proxy includes two properties:

• ErrorMessage – Contains the value of the Message property returned in the response when the Status property is set to a non-zero value; otherwise, it will be null.
• Response – Contains the value of the Data property returned in the response when the Status property is set to zero; otherwise, it will be null.

If the call returned a non-zero Status value, the Intranet will log the error, and the proxy will return an empty 500 HTTP response in the same manner as the Simple endpoint error handling.

Unauthenticated Customers /AnonysmousProxy/ and /AnonysmousProxySimple/

Because the eCommerce Shop experience doesn't rely on the users being logged in, using the unauthenticated endpoints is usually more appropriate. This endpoint uses the prefix /AnonysmousProxySimple/ in the API call. The endpoints behave in the same manner as the Authenticated Customer endpoints except:

• The authenticatedAssociateId parameter is NOT added to the requests to Disco because the user is not logged in.
• The paths of the endpoints require the name of the client to be passed.
  • Simple Endpoint: https://api.directscale.com/AnonysmousProxySimple/{client}/{the rest of the path}
  • Standard Endpoint: https://api.directscale.com/AnonysmousProxy/{client}/{the rest of the path}

📘Note

The /AnonymousProxy/ requires a status code of "0".

Authenticated Admin Users /Admin/Proxy/

There is only one authenticated Admin user proxy endpoint. It's called by Admin custom content pages. The /Admin/Proxy/ endpoint behaves in the same manner as the Authenticated Customer Simple endpoint except:

• The authenticatedAssociateId that is passed to Disco by the proxy is the ID of the logged-in Admin user NOT the ID of a logged-in customer.
• The path of the Admin endpoint is: https://api.directscale.com/Admin/Proxy/{the rest of the path}.