Part 1: Welcome to the Zendesk platform

Welcome to the Zendesk Platform!

If you don't know what that means, you're in the right place. This guide was created to help the large number of non-technical people looking to build on our platform. We understand that the idea of coding, especially when you've never written a single line, may be daunting and scary, but this guide will break it down, step by step, ensuring that you not only understand our API and platform, but you'll actually learn how to code along the way. We hope you're excited and ready to learn!

This tutorial assumes you use a Mac and Chrome as their browser.

Topics covered:

• What's a platform
• What's an API?
• How does it work?
• What do I need to make a request?
• What's JSON?
• Let’s test it!

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not provide support for the content. Please post any issue in the comments section or search for a solution online.

What's a platform?

A computer platform, in it’s most basic sense, is the pre-existing environment that computer software is designed to work with. For example, Twitter is a service almost everyone is familiar with. You can create tweets, retweet, and follow people. Twitter is a platform that then allows people to build on top of and manipulate to fit their needs. You want a bot that follows every account that has “cats” in the name? You can do that because of their platform.

By the end of this guide, you'll have done the following:

• Learned about Rest APIs, requests, and cURL statements
• Learned JavaScript so you can call APIs and make requests on the Zendesk platform
• Installed Sublime Text to edit and save our code
• Set up a developer environment on your computer to build apps
• Worked your way through our most commonly used APIs and authentication
• Created a Github repo of scripts, built by you
• Created and populated a robust test account

What's an API?

To understand what an API is, first let's think about a technical product we all use, like Zendesk Support. Support is a piece of software that brings companies and their customers closer together. There are many things that Support lets you do, such as:

• create tickets
• add & update users
• create groups
• suspend users
• mark comments as private
• customize your Help Center
• etc.

All of these actions that Zendesk Support can do are part of our API. Simply put, an API is a group of things that software can do. (See, that's not scary to understand.) By accessing an API, you have the power to do all of these things too!

Before building with our API, you'll want to read our overview of rules and guidelines, which you'll find here: https://developer.zendesk.com/rest_api/docs/core/introduction.

You'll want to be familiar with this later on when you decide to build something for real.

How does it work?

Our API is a RESTful one. You can read the deep deep details of REST here, but for the purposes of this tutorial and getting started, here's what you need to know:

• REST stands for Representational State Transfer. It is sometimes spelled "ReST"

• You'll see verbs or terms like GET, PUT, POST, and DELETE (written just like that, all caps)

• These terms are also known as HTTP methods or protocol (sometimes just HTTP)

• Think of them like so:

  What is does	Term to use
  to create	POST
  to retrieve	GET
  to update	PUT
  to delete	DELETE

• HTTP protocol is used to make calls between machines by sending requests to GET information or DELETE data

• After a request is made, the computer returns a response in JSON

What do I need to make a request?

Depending on how you make the request (and we’ll talk more on that in a bit), you’ll need the following information:

• Subdomain - The subdomain is another term for your Zendesk Support account. When you sign up for a Support account, you're asked to create a subdomain. Our support subdomain is ‘support’, and when entered, it formats like so: https://support.zendesk.com/

• Email - Your email address used with Zendesk Support

• Password - Your Zendesk Support password

• API token - API tokens are managed in the Support Admin interface at Admin > Channels > API. The page lets you view, add, or delete tokens. More than one token can be active at the same time. Deleting a token deactivates it permanently.

  If using an API token, use the following authentication format:

  {email_address}/token:{api_token}

What's JSON?

• JSON: JavaScript Object Notation

• JSON is a syntax for storing and exchanging data. In other words, it's a language and format used to send and receive information

• JSON is structured like so:

  

Let’s test it!

1. Open up a new browser window or tab.

• Sign in to your Support instance at https://{subdomain}.zendesk.com/agent.

  Your "subdomain" is your Support account name. For example, my subdomain is 'catzomg' (because that's what I registered), so I enter that as my subdomain and get https://catzomg.zendesk.com/agent.

  Be sure to delete the curly braces. They're not needed to run the call.

• Once signed in, go to:

  https://{subdomain}.zendesk.com/api/v2/users/me.json

• Voila, you just made a call to the Zendesk Support API and got your account info!

  

• If you're curious about what just happened, right click the web page and click Inspect Element. If you aren't on Chrome, I suggest switching to it so you can follow along without issues.

• With Inspect Element, a developer console pops up on the bottom of your web page. Navigate to the Network tab and click it. It'll look like this:

  

• Refresh your page. In the Network tab, you’ll see your completed request:

  

Once you feel comfortable with the information in this part, be sure to continue on with Part 2.