zd-api-lib

Overview

zd-api-lib is a library to simplify Zendesk API usage. Currently in progress, not all endpoints are supported.

Supported endpoints and requests:

tickets: ['list', 'listAll', 'show', 'create', 'update', 'delete', 'deleteMany'],
ticketFields: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
ticketForms: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
organizations: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
users: ['list', 'listAll', 'listByGroup', 'show', 'create', 'update', 'delete'],
userFields: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
customRoles: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
groups: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
group_memberships: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
macros: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
automations: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
triggers: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
triggerCategories: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
views: ['list', 'listAll', 'show', 'create', 'update', 'delete'],
search: ['list', 'listAll']

Installation

You can install zd-api-lib via npm:

npm install zd-api-lib

Usage

- Set a variable to "new Zendesk(config)"
    - If {'username': false}, oAuth authentication will be used, otherwise basic authentication is used
    - Example for oAuth: 

    ```Javascript
    let zendesk = new Zendesk({
        'url': 'https://{subdomain}.zendesk.com',
        'username': false,
        'token': oauthToken
    })
    ```

- Here's a basic example of how to use `zd-api-lib`:

```javascript
var Zendesk = require('zd-api-lib');

let zendesk = new Zendesk({
    'url': 'https://{subdomain}.zendesk.com',
    'oauth': true,
    'token': api_or_oAuth_token
})

zendesk.users.list().then(users => {
    console.log(users)
})
```

Rate Limits

- Zendesk's default api rate limit is 700 requests / min 
- Config object supports optional rateLimit key with the following format:

    rateLimit: {
        retryAfter: bool,
        rates: {
            base: num,
            slow: num,
            lowLimit: num
        }
    }

- retryAfter:
    - If true, will use the retry-after header returned in a 'tooManyRequests' error to resend the request
    - Max Retries default = 3 
- rates:
    - base: default requests per minute to use for the script
    - slow: optional slow requests per minute to throttle requestrate
    - lowLimit: When number of requests remaining hits this value, use the slow rate
        - uses 'x-rate-limit-remaining' header returned in requests
- Rate limits are done by setting a timeout for 60000 / currentRPM after a requests

Functions

list(pageLimit, params, includes)

• Sends a GET request
  • Equivalent to the /{type}.json endpoint.
  • Example to get one page of users:

zendesk.users.list(1).then(users => {
    console.log(users)
})

• Page limit of 0 will return all pages

• If any sideloads are included, returns an object:

{
    data:[...],
    sideload1:[...],
    sideload2:[...],
    [...]
}

• If using the Search endpoint, the query contents should be URI encoded
  • Example to find all tickets created between two dates, including sideloaded users:

let ticketDate = {
    start: '2024-10-01T00:00:00Z', 
    end: '2024-10-15T00:00:00Z'
}
let query = `type:ticket created>${ticketDate.start} created<${ticketDate.end}`;
let tickets = await zendesk.search.listAll(`query=${encodeURIComponent(query)}`, ['tickets(users)'])

listByGroup(groupId, params)

• List all users in specified group ID
  • Example:

zendesk.users.listByGroup(12345).then(users => {
    console.log(users)
})

show(id)

• Retrieves a specific user by ID
  • Example:

zendesk.users.show(12345).then(user => {
    console.log(user)
})

showMany(ids)

• Retrieves multiple users by their IDs
  • Example:

zendesk.users.showMany([12345, 67890]).then(users => {
    console.log(users)
})

create(data)

• Creates a new user with the provided data
  • Example:

let newUser = {
    name: 'John Doe',
    email: '[email protected]'
}
zendesk.users.create(newUser).then(user => {
    console.log(user)
})

createMany(data)

• Creates up to 100 objects per request
  • Currently does not split up groups of more than 100
• Data should be an array of objects to create
  • Object format is also accepted if key is correct for endpoint:

{ 
    "tickets": [
        {"subject": "1",...},
        {"subject": "2",...}
    ]
} 

• Example to create multiple users:

let newUsers = [
    { name: 'John Doe', email: '[email protected]' },
    { name: 'Jane Smith', email: '[email protected]' }
]
zendesk.users.createMany(newUsers).then(users => {
    console.log(users)
})

createOrUpdate(data)

• Creates a new oject or updates an existing obect with the provided data
  • Example:

let user = {
    name: 'John Doe',
    email: '[email protected]'
}
zendesk.users.createOrUpdate(user).then(user => {
    console.log(user)
})

update(id, data)

• Updates a specific object by ID with the provided data
  • Example:

let updatedUser = {
    name: 'John Doe',
    email: '[email protected]'
}
zendesk.users.update(12345, updatedUser).then(user => {
    console.log(user)
})

delete(id)

• Deletes a specific object by ID
  • Example:

zendesk.users.delete(12345).then(response => {
    console.log(response)
})

deleteMany(ids)

• Deletes multiple objects by string or array of IDs
  • Example:

zendesk.users.deleteMany([12345, 67890]).then(response => {
    console.log(response)
})

License

This project is licensed under the MIT License. See the LICENSE file for more information.