What Is a JSON Endpoint? Definition and Example
A JSON endpoint is a URL on a server that returns data as JSON instead of an HTML page. A browser shows HTML to a person. A JSON endpoint sends data to a program.
JSON is short for JavaScript Object Notation. It is a plain text format built from key and value pairs, lists, numbers, strings and the values true, false and null.
Every JSON endpoint is an API endpoint. The name only adds the fact that the reply is JSON.
A request and the reply
Ask for a list of users at one URL.
GET https://api.example.com/users
The server replies with a status line, headers and a body.
200 OK
Content-Type: application/json
{
"users": [
{ "id": 1, "name": "Ana Silva", "email": "ana@example.com" },
{ "id": 2, "name": "Wei Chen", "email": "wei@example.com" }
],
"total": 2
}
The body is the data. No page layout, no styling, no scripts.
What makes it a JSON endpoint
Three things have to be true.
| Part | Requirement |
|---|---|
| Response header | Content-Type: application/json |
| Response body | Valid JSON that a parser accepts |
| Status code | 200 for success, 4xx for a client mistake, 5xx for a server fault |
The header matters as much as the body. Many client libraries decide whether to parse the reply by reading that header first.
The methods a JSON endpoint accepts
One URL usually serves several actions, split by HTTP method.
| Method | Meaning | Usual reply |
|---|---|---|
| GET | Read data. | 200 with the records |
| POST | Create a record. | 201 with the new record |
| PUT | Replace a record. | 200 with the updated record |
| PATCH | Change part of a record. | 200 with the updated record |
| DELETE | Remove a record. | 204 with an empty body |
Public endpoints you can try
You can test a JSON endpoint without writing any code. Paste one of these into a browser tab.
| URL | What it returns |
|---|---|
jsonplaceholder.typicode.com/posts | A list of fake blog posts for testing. |
jsonplaceholder.typicode.com/users | A short list of fake user records. |
ip-api.com/json | The location guessed from your own address. |
From a terminal the same request looks like this.
curl -s https://jsonplaceholder.typicode.com/users/1
Add -i to see the headers. That is the fastest way to confirm the content type.
How an endpoint is described
Endpoints are described by path, method and shape of the reply. Teams publish that description so other teams can build against it.
The common formats are OpenAPI for REST services and JSON Schema for the body itself. A schema states which fields exist, which are required, and what type each one holds.
Tools like Postman read those files and build a request form for you. That is why the same URL is called an API endpoint there.
Problems that come up most
- Wrong content type. The body is JSON but the header says
text/html, so the client refuses to parse it. - An error hidden inside a 200. The status says success and the body says
"error". Return the real status code instead. - Blocked by the browser. A page on another domain needs the right cross-origin headers, or the request fails before the data arrives.
- No pagination. An endpoint that returns every row will time out once the table grows. Return a page and a cursor.
- Fields that appear and vanish. Removing a field breaks every client. Add fields, and retire old ones behind a version.
JSON or XML for the reply
JSON has largely replaced XML for web and mobile APIs. It is shorter, and every major language parses it without an extra library.
XML still wins where a strict contract or a signed document is needed. The longer comparison is in XML or JSON, which is better.
How to Prepare
- Build one endpoint yourself. Return a list, add a filter, then add paging. Doing it once teaches more than reading about it.
- Read the status codes. Know 200, 201, 204, 400, 401, 403, 404, 429 and 500, and when each is correct.
- Practice the API design questions. Grokking System Design Fundamentals covers request formats, paging and rate limits.
- Design a full service. Grokking the System Design Interview shows where endpoints sit next to caches, queues and databases.
- Say the contract out loud. In a mock interview, name the path, the method and the reply shape before you draw anything.
GET YOUR FREE
Coding Questions Catalog
$99
$197
$72
