REST API glossary

This article provides a glossary for a number of common terms that you may come across when using our REST API.

• API
• REST
• JSON
• CRUD
• Endpoint
• HTTP response status codes
• Payload

API

API stands for Application Programming Interface, which doesn't really explain much. Think about it like this: An API receives inbound requests and sends outbound responses. You make a request, the API passes that request to a server, and then waits for the server's response. As an application's user interface (UI) lets users interact with it, an application programming interface (API) lets clients interact with the application. It's just another way to interact with a system and its functionality.

REST

REST stands for REpresentational State Transfer. A REST API is one that adheres to six specific architectural constraints that make interacting with them easier and less resource intensive.

For details, see Representational state transfer on Wikipedia.

JSON

The Zendesk API is a JSON API, meaning it only accepts and returns JSON data.

JSON stands for JavaScript Object Notation, but don't let the JavaScript part throw you off. JSON is not a programming language: it's a human-readable data format. The JSON format can be used to store and transfer information in a standard way.

JSON adheres to a strict syntax. Mind your commas, colons, parentheses, and curly braces ({}). They'll be your best friends and worst enemies.

To highlight just how readable JSON is, here's a syntactically (and factually) correct JSON object that you'll be able to interpret without even knowing anything about JSON yet:

{
  "facts": {
    "name": "Greg",
    "is_cool": true
  }
}

To learn more, see Working with JSON.

CRUD

Create, Read, Update, Delete. Think of them as verbs. They tell the API to create, read, update, or delete records. On the Internet, the four verbs correspond HTTP request methods: GET (read), PUT (update), POST (create), DELETE (delete). There are more than these four request methods but these are the most common.

A GET (read) request is the most basic HTTP method. You use it all the time when browsing the web. For example, when you use Google search, your web browser makes one GET request after another.

Endpoint

You use endpoints to actually call an API. As the word implies, an endpoint is the location that receives web requests. An API is a collection of endpoints. Each endpoint has its own rules on CRUD operations.

HTTP response status codes

When you make a request to an endpoint, the server:

1. Looks at the information sent.
2. Looks for the resource referenced in the request.
3. Checks if you have permission to access it.
4. Returns a response with a status code.

Each status code has a specific meaning. They are grouped together conveniently into the following five groups:

• (100-199) Informational responses
• (200-299) Successful responses
• (300-399) Redirect messages
• (400-499) Client errors (you messed up)
• (500-599) Server errors (the server messed up)

For details, see List of HTTP status codes on Wikipedia. It's not a definitive list and some infrastructure companies like Cloudflare have their own set of status codes. Keep this in mind if you see a strange new status code that you can't find anywhere.

Payload

As a ship carries a payload to a port, some HTTP requests carry a payload to an API. HTTP requests that create records or update existing records also need to carry the data to the API. For example, when creating a user in Zendesk with the API, you need to send the user information to the API. The payload contains the new user information (in JSON format) that the API will use to create the user in Zendesk.