If you're just starting out, be sure to check out Part 1 of this tutorial. If you're comfortable with everything in that section, awesome job! In Part Two, we'll learn how to read all the data being sent back to us, install curl so we can make HTTP requests from the terminal, and we'll complete our developer environment. Ready, set, let's go!

JSON responses

You may have realized that when you make a call on your browser, the response (or what the computer presents you to read), is a big mess and hard to actually read:

To fix this:

  1. Download a JSON formatter to pretty print* your responses. (You can download whichever one you like, this is just one of many available).

  2. Once installed, refresh your browser and enjoy the gorgeous JSON:

Pretty printing is the application of various stylistic formatting conventions to text files, such as source code, markup, and similar kinds of content. These format changes can adjust positioning and spacing (indent style), add color and contrast (syntax highlighting), adjust size, and make similar modifications intended to make the content easier for people to view, read, and understand. Pretty printers for programming language source code are sometimes called code beautifiers or syntax highlighters.

Using curl

Making calls in your browser is pretty great, but what about when you want to work directly from the command line, or create a ticket with multiple fields? This is when you’ll want to use a curl statement. curl is a lightweight, command-line tool for making HTTP requests without a web browser. Just how the request shows up in the developer console on a browser, when you make a request using curl, all the information is given to you directly in the command-line window. (There’s an example below we’ll work through after installing this.)

All the examples in the Zendesk REST API docs consist of curl statements. A statement is simply a complete expression of code, like so: var x = y * z + 12

You can run these statements on your command line (also known as your terminal) to try out various requests.

To get curl or check what version you may already have, take a look at this tutorial we put together. Follow all the steps, get set up, and run a test statement to ensure it works. (Be sure to use the correct signin info for your Zendesk Support account while running these tests.)

And lastly, if you don't already have a Support account/subdomain, I recommend signing up for a Trial account here so you can play with the API freely without altering up your work account.

If you really get into developing apps and scripts to enhance your support experience, Zendesk does offer sponsored testing accounts. Just email [email protected] and we can extend the trial.

Second example - Common ask: Help, I want to quickly get all tickets in my Support product!

  1. Because we want to read data, we'll use the GET method.

    The Tickets API documentation supplies us with the call to make: GET /api/v2/tickets.json.

    Note: You have to be an admin in Zendesk Support to use this endpoint. See Understanding Zendesk Support user roles in the Support Help Center.

  2. Open a basic text editor and paste this curl statement (it's easier to edit in a text editor than the terminal because the terminal doesn't register mouse clicks):

    curl https://{subdomain}.zendesk.com/api/v2/tickets.json \  -v -u {email_address}:{password}
  3. Replace the generic fields with your Zendesk Support info. Remember to delete the curly braces, they are not needed to run the call.

  4. Next, open up your computer's terminal/command line.

    On a Mac, press Cmd + Space Bar, then type 'terminal'.

  5. Paste the edited curl statement into the terminal and hit Enter.

Assuming you have tickets in your Support account, your response will look like this:

You're probably asking yourself, "How does the computer know we want to get that info? We didn't put GET in the CURL statement."

  • There's a format for each type of request. We don't have to say GET in our request because by default, the computer will fetch this information since we didn't supply it with a reason to do anything else.

  • An example POST statement looks like this:

    curl https://{subdomain}.zendesk.com/api/v2/tickets.json \  -d '{"ticket": {"subject": "My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}' \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST

    By adding additional content and the -X POST, we change the request. More information on requests here.

Let's pick a language

Okay so that last example was probably a lot of information, so let's figure out what's going on! To start, we need to pick a language to use. Why? Calling requests with the browser (like our first example), or curl (like our second example), is great, but sometimes we want more robust information or want to create a lot of data at once. To really dive into our Support product and customize it completely, we need to write some scripts, or code.

We write a lot of JavaScript (JS) at Zendesk, and because it's easy for beginners to pick up, it's perfect for us to use here. Also, JS is already installed on your computer and we don't need to set anything up. Take a deep breath and let's try it out:

  1. Let's go back to our browsers. Right click and select Inspect Element to bring up your console.

  2. Navigate to the Console tab and click it. It'll look like this:

    The console is your best friend. It is also commonly referred to as a 'command line' or 'browser's terminal'. Simply put, you write something in the console, hit 'Enter', and the computer will immediately give you an answer. It's great for learning and just playing around.

  3. In your console, type var x = 5 and then press Enter.

  4. Now type x and hit Enter. What just happened? The console returns 5 because we just assigned it to x.

We won't go into the full syntax of JavaScript here, but this is a great resource for beginners: http://jsforcats.com/#basics. Silly name, yes, but simply done, and brilliant. Explore this a bit now (at least the basics), and when you're ready to start building more, you can get through all of it in an hour or two.

And remember, don't get too caught up trying to remember how to do everything (because you won't be able to). We recommend writing a few lines, seeing what happens, and then getting back to this tutorial. We'll be linking articles throughout this guide so that as you work through it, you have additional resources for when you're ready to learn more.

Time to complete our developer setup

So far we've learned briefly about RESTful APIs and written a bit of basic JavaScript---but we don't have anywhere to save our code yet!

Code can easily be edited in a simple text editor, but developers often use specialized applications that are more comfortable for writing and editing code. Examples include TextEdit or Xcode.

There are tons of editors available, but to keep things simple, let's all work on Sublime Text. It's donation-based, simple, and easy to use.

  1. If it's not already installed, download Sublime Text.

  2. Once you have Sublime Text, open it up and take a look. You can copy this code and paste it in your blank editor:

    var x = 10;var y = 5;
    var z = x + y;
    print var z

    Your editor should look like this:

    In the right, bottom corner, you'll see that it says 'Plain Text', by default. When you're ready to save your code, make sure it has the proper file extension. For example, when you save slideshows, you use '.key' or '.ppt'. For JavaScript files, we save everything with a '.js' extension.

    If you want to learn more about different file extensions and when to use which one, take a look at this resource.

  3. Go ahead and save the file as example.js. You should see a change in format, like this:

Something to note: Line 6 is different than all the others--I forgot a semicolon and the editor has highlighted that for me. That's the beauty of text editors. There are many ways to customize yours to make it as efficient for you as you need it. My favorite to start off with is JSHint. JSHint is a tool to detect errors and potential problems in JavaScript code.

Important: I personally would not bother with Sublime customizations now, as it may only confuse you starting out. Write some JavaScript on jsforcats, get used to it, then worry about making your editor cool and beautiful. BUT, if you want to, I'll list the steps below.

To install JSHint, follow these steps:

  1. Install Sublime's Package Control. This manages all your installs and makes it easy to keep track of and access. The manual install may be easier.

  2. Let's install Node.js. I could try to explain what exactly Node is right now, but for simplicity reasons, just know that with Node installed, unpacking other modules and programs will be super quick and easy and your life will be better. Trust me.

  3. Install JSHint for Sublime Text by following the instructions here. Since we just installed Node, you can simply run npm install jshint in your terminal (command line).

If you get stuck, be sure to check each component was properly installed.

Before moving on to Part 3: Using Zendesk APIs of this tutorial, make sure you've completed all of the above steps and you feel comfortable with your setup.