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!
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
, andDELETE
(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 orDELETE
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!
- 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.
2 Comments
Awesome!
This page describes how to invoke the API but it doesn't guide me through a real-world scenario that the Zendesk API supports. From a business perspective, I'm still struggling to understand how the API is useful. What process is Zendesk improving?
It's like if someone built a car and shows me the steering wheel, pedals, etc,.. without explaining to me what the car is for in the first place. I need to know what the "car" is for (not its parts) to understand the "value" I can get out of using the car.
We only tested the API itself but not the outcome of the scenario that it was intended to support.
Please sign in to leave a comment.