Issuing REST Requests from the Swagger Web UI

The Swagger Rest API page provides a learning interface that helps you formulate and execute well-formed REST requests to the associated NC queue. The web UI page shows a construction of the REST request and response text in curl command and JSON language formats.

Here are the steps to formulate and execute a REST request:

  1. Access the VOV REST API page in a browser. The URL is shown by the command nc cmd vovbrowser -url /html/vovrest.html.
  2. If SSL/TLS is enabled for the NC queue, then select the https URL in the the "Server" drop-down menu on the left side of the page near the top.
  3. Scroll down to the Object-Verb section for the desired REST request.
  4. Click on Try it Out on the right.
    This activates a web form on the page to accept your specified parameters for a REST request before executing it.
  5. Edit the parameters for your REST request in the web form.
    Example A

    If you are selecting a GET operation on a job object, the job id and sometimes a job object field name are required. Enter these items in the web form.

    Example B

    If you are selecting a POST operation on a job object to submit a job to Accelerator, the parameters are more extensive. Edit the job creation parameters box. A template window in the web form illustrates the format, which is consistent with a Python dictionary syntax with keyword/value pairs. Replace the template with your desired job creation specifications.

    Most of the keyword/value pairs in the template for job creation are optional, but a few are required. A simple and minimal working example job creation parameter list follows. To specify other properties of a job, choose some additional keywords from the template text that appears pre-populated in this sub-window.
           "command" : "sleep 60",
           "logfile" : "JOBLOG.01",
           "rundir"  : "/tmp",
           "env"     : "BASE"
  6. Click the blue Execute button.
    This sends the REST request.
  7. Scroll down to see the Server Response. A code of 200 - 299 indicates success.
  8. Troubleshoot if the request failed. Common errors and remedies include:
    1. If error text is "Bad Request", then check that the right URL is selected in the Servers drop-down menu at the upper left.
    2. If an authentication error is seen, logout of the web UI and then log in again so the Swagger page gets a fresh JWT access token.
    3. If an error with "Error: Bad Request" is seen, check the specified text in the Job Control Parameters sub-window. A common mistake is to add an invalid comma after the last keyword/value pair.
    4. A server error is returned if you specify a job logfile that is the same as another job in the system. Change the logfile name and retry the request.