Remote Web API Methods

Remote API Methods allow you to develop stand-alone applications that can communicate with the wbTeamPro database. wbTeamPro uses a RESTful Service Model to provide remote access to the data and data operations within the system. Method requests made to the Remote API utilize the HTTP protocol, with all payload data being submitted and returned in the JSON format.

Using the API Developers Sandbox

Included with your installation package is an API Developers Sandbox script that allows you to view and test the methods provided by the Remote API. The API Developers Sandbox source code also serves as a PHP example of how to perform a request and parse the results.

To use our API Developers Sandbox you will need to upload the API Developers Sandbox folder included with your installation. Once uploaded you will access the sandbox.php file and be prompted to enter the API URL, API User, and API Pass for the sandbox to use when connecting to your server. The API URL will be a url pointing to the wbTeamPro api.php file (ie: {yourwebsite_url}/modules/addons/wbteampro/api.php). The API User must be an administrator that has an Administrative Role that was give access to the wbTeamPro system.

Anatomy of an API Request

Remote API requests are made by querying the api.php file provided with your installation. API Requests can be constructed using a "Clean URL" format, where each request URL will define the resource request being performed. Optionally the resource "action" can be passed as a parameter with the request.

  • Rewrite (standard)
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/projects/100/json?params={...}

  • Rewrite (translation using included htaccess)
    {yourwebsite_url}/modules/addons/wbteampro/api/v1/projects/100/json?params={...}

  • Direct URL Example
    {yourwebsite_url}/modules/addons/wbteampro/api.php?action=v1.projects.100.json&params={...}

The response provided by the Remote API is encoded in either a JSON or XML format, defined as the last key the resource "action" request chain.

  • JSON Response Format
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/projects/100/json

  • XML Response Format
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/projects/100/xml

When performing a Remote API request the following information must be provided:

  • API USERNAME (username=adminuser)
    This is a valid Administrator username that is within a WHMCS Administrative Role that has been granted access to the wbTeamPro system.

  • API PASSWORD (password=MD5HASH)
    This is the password for the valid Administrator, encoded into an MD5 HASH.

    The wbTeamPro API will ban the IP address of any connection that fails to login after 3 attempts. Banned IPs are stored in the WHMCS bannedips table.

  • API VERSION
    The API Version is specified as the FIRST key in the RESOURCE ACTION chain (ie: v1.project.100.json).

  • API RESPONSE FORMAT
    The API Response Format (json or xml) is specified as the LAST key in the RESOURCE ACTION chain (ie: v1.project.100.json).

  • HTTP METHOD (method=get)
    The http method defines the operation to be performed on the requested resource. The http method value can be passed as the parameter "method", or by using the correct http mehod for the request. The following http methods are allowed:

    • GET - Retrieve a record (or list of records)
    • PUT - Update a record
    • POST - Create a record
    • DELETE - Delete a record
  • RESOURCE ACTION (action=v1.projects.100.json)
    The resource action represents the method request chain for the query, specifying the Version, Method(s), and Response Format. For example, the resource action "v1.projects.100.json" would instruct API V1 to perform an action on Project ID #100 and return the results in the JSON format.

  • RESOURCE PARAMETERS (params={"project_id":"100"})
    The request parameters are additional values, unique for each method, that control or filter the resource request being performed. The params value can be provided as an ARRAY or JSON string.

  • Combining Resources
    Resource requests can be chained together to create a more comprehensive response, minimizing the number of requests needed for simple operations. For example, to load a project and the actions for the project, you can create a single request that will return the response from both resourses.

  • Example A - Perform Dual Requests
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/projects/100/json
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/actions/json?params={"project_id":"100"}

  • Example B - Perform a Combined Request
    {yourwebsite_url}/modules/addons/wbteampro/api.php/v1/projects/100/actions/json

Anatomy of the Response

The response data, whether in JSON or XML, will decode into an object containing a request and response dataset. In the following example we have requested all Tickets for Project #100.

stdClass Object (
  [request] => stdClass Object
    (
      [action] => projects/219/whmcstickets
      [method] => GET
      [format] => json
      [code] => 200
      [message] => Success
    )
  [response] => stdClass Object
    (
      [data] => stdClass Object
        (
          [total] => 1
          [page] => 1
          [pages] => 0
          [limit] => 50
          [offset] => 0
          [filters] => stdClass Object
            (
              [project_id] => 219
            )
        )
      [project] => stdClass Object
        (
          [project_id] => 219
          ... project fields ...
        )
      [whmcstickets] => Array
        (
          [0] => stdClass Object
            (
              [id] => 2038
              ... ticket fields ...
              [ticketxref] => stdClass Object
                (
                  [xref_id] => 91
                  ... ticketxref fields ...
                )
            )
        )
    )
)

Remote API Resource Action Reference

Please use the API Developers Sandbox to learn more about the request parameters required and response data provided by the following methods.

api

  • findResources: api.resources
    Return the API Resource List

config

  • getConfig: config
    Return a Config Option

projects

  • findProjects: projects
    Return a Project List
  • createProject: projects
    Create a Project
  • getProject: projects.{project_id}
    Return a Project
  • getProjectActions: projects.{project_id}.actions
    Return a Project Action List
  • getProjectTopics: projects.{project_id}.topics
    Return a Project Topic List
  • getProjectFiles: projects.{project_id}.files
    Return a Project File List
  • getProjectTickets: projects.{project_id}.whmcstickets
    Return a Project Ticket List
  • getProjectTimelogs: projects.{project_id}.timelogs
    Return a Project Timelog List
  • updateProject: projects.{project_id}
    Update a Project
  • deleteProject: projects.{project_id}
    Delete a Project

actions

  • findActions: actions
    Return a Action List
  • createAction: actions
    Create a Action
  • getAction: actions.{action_id}
    Return a Action
  • getActionTopics: actions.{action_id}.topics
    Return a Action Topic List
  • getActionFiles: actions.{action_id}.files
    Return a Action File List
  • getActionTickets: actions.{action_id}.whmcstickets
    Return a Action Ticket List
  • getActionTimelogs: actions.{action_id}.timelogs
    Return a Action Timelog List
  • updateAction: actions.{action_id}
    Update a Action
  • deleteAction: actions.{action_id}
    Delete a Action

topics

  • findTopics: topics
    Return a Topic List
  • findTopicThreads: topics.bythread
    Return a Topic Thread List
  • createTopic: topics
    Create a Topic
  • getTopic: topics.{topic_id}
    Return a Topic
  • updateTopic: topics.{topic_id}
    Update a Topic
  • deleteTopic: topics.{topic_id}
    Delete a Topic

files

  • findFiles: files
    Return a File List
  • findFileThreads: files.bythread
    Return a File Thread List
  • createFile: files
    Create a File
  • getFile: files.{file_id}
    Return a File
  • downloadFile: files.{file_id}.download
    Download a File
  • updateFile: files.{file_id}
    Update a File
  • deleteFile: files.{file_id}
    Delete a File

whmcstickets

  • findWHMCSTickets: whmcstickets
    Return a WHMCS Ticket List
  • getWHMCSTicket: whmcstickets.{ticket_id}
    Return a WHMCS Ticket

ticketxrefs

  • findTicketXrefs: ticketxrefs
    Return a TicketXref List
  • createTicketXref: ticketxrefs
    Create a TicketXref
  • getTicketXref: ticketxrefs.{xref_id}
    Return a TicketXref
  • updateTicketXref: ticketxrefs.{xref_id}
    Update a TicketXref
  • deleteTicketXref: ticketxrefs.{xref_id}
    Delete a TicketXref

timelogs

  • findTimelogs: timelogs
    Return a Timelog List
  • createTimelog: timelogs
    Create a Timelog
  • getTimelog: timelogs.{timelog_id}
    Return a Timelog
  • updateTimelog: timelogs.{timelog_id}
    Update a Timelog
  • deleteTimelog: timelogs.{timelog_id}
    Delete a Timelog