SDAPI How to Write a Client 2.0

The Script Debugger API (SDAPI) is a RESTful service that enables you to interact with the script debugger engine. You use the SDAPI to enable the debugger, to set breakpoints, and to interact with halted script threads.

The following sections describe the steps you must perform to create a client application

Authorization and Identification

All SDAPI requests must:

  • Use the HTTPS protocol with BASIC authentication, where the credentials represent a Business Manager user with the WebDAV_Manage_Customization functional permission.
  • Specify a client application identifier as an HTTP header, where the header key is x-dw-client-id and the value is a string representing your client.
  • Use the Sites-Site context in the request URL (/s-/):
    https://your_host_name/s/-/dw/debugger/v1_0/

See Client Resource section for more information.

Enabling the Debugger

To enable the debugger, issue a POST request to create a Client resource. To disable the debugger, issue a DELETE request to remove the Client resource. Removing the Client resource also removes all breakpoints and resumes all halted script threads.

Important: When finished debugging, always remove the Client resource. Leaving the debugger enabled negatively impacts performance.

Setting Breakpoints

After creating the Client resource, you can create a breakpoint using a POST request. See Breakpoints to understand how to create, delete, and fetch breakpoints.

Note: If you change your script file after creating a breakpoint, update your breakpoint location accordingly.

Interacting with Halted Script Threads

When you set a breakpoint in a script and the breakpoint is hit, the debugger engine halts the script thread so you can interact with it. To interact with the script thread, you can:

  • Inspect variables: see Object members to understand how to see the values of variables in the context of a script thread.
  • Evaluate expressions: see Evaluating Expressions to understand how to evaluate an expression in the context of a script thread.
Note: You typically fetch script threads by making a GET request in a separate application thread. This allows you to repeatedly query the debugger engine for halted script threads, which you can then use to update your client application user interface.
Important: The debugger engine allows a script thread to be halted for up to one minute. To keep a script thread alive, you must reset the timeout threshold. Keeping the thread alive ensures that you have time to inspect variables and evaluate expressions. See Script Threads to understand how to reset the timeout threshold.You typically reset script threads in a separate application thread. By repeatedly resetting the timeout threshold, you ensure that your script threads are not terminated.