Contents
How JSON came about
Douglas Crockford made JSON popular in the early 2000s. It was officially described in 2002. Over time, JSON became a standard way for computers to exchange data, recognised and approved by various groups as a common format.
How JSON works
JSON follows a few simple rules:
– Curly braces {} represent “objects,” collections of “name: value” pairs.
– Square brackets [] represent “arrays,” which are ordered lists of values.
– A colon : separates a name from its value.
– Commas , separate different items in a list.
Because it’s simple and consistent, JSON is ideal for sending information between computer programs, especially for websites and apps to get data from servers (APIs).
How a JSON response is structured
When you ask a website or app for information, and it sends back JSON data, that message has three main parts:
Status line
The status line is always the first line in the response. It looks something like this:
HTTP/1.1 200 OK
– HTTP/1.1: This is the version of the web language being used.
– 200: This is a special number called a “status code.” 200 means “OK” or “success.” Other common codes include 404 (meaning “not found”) or 500 (meaning there was a server error). Your computer uses these numbers to know what to do next.
– OK: This is a short, human-friendly message that explains the status code.
Headers
After the status line, you’ll see several “headers.” Each header is a pair of information, like a label and its value, separated by a colon. For example:
– Content-Type: application/json: This is a very important header. It tells your computer that the main part of the message (the “body”) is in JSON format. Your computer needs this to know how to read the data correctly.
– Other headers might include Content-Length (telling you the size of the data in bytes), Server (telling you about the server sending the data), or Date (when the message was sent). These extra headers help your computer handle the data or can be useful for fixing problems.
Body
After a blank line following the headers, comes the “body.” This is where the actual JSON data lives. This data is text, usually in a format called UTF-8.
The JSON data in the body follows simple rules:
– Objects: Use curly braces {} to hold a collection of “name: value” pairs. For example, {“name”: “Wes”, “age”: 30}.
– Arrays: Use square brackets [] to hold a list of values. For example, [“apple”, “banana”, “cherry”].
– Names and text: Words and text (like “name” or “Wes”) are put in double quotes “”.
– Separators: A colon : separates a name from its value, and a comma , separates different items in a list.
JSON can handle different types of data, like text (strings), numbers, true/false values (booleans), empty values (null), objects, and arrays. This makes it very flexible for organising complex information.
When your computer receives this JSON text, it uses special tools (like JSON.parse() in JavaScript) to turn it into something your programs can easily use and work with.
Official rules for JSON
JSON has many official rules that define how it should be structured and used. These rules help different computer systems understand each other when they send and receive JSON data.
JSON:API
JSON:API is a set of strong rules for building APIs (ways that computer programs talk to each other) using JSON. It makes sure that all requests and responses look the same. It helps organise how data is shown, how related information is linked, how to handle long lists of data (pagination), and how to ask for only specific parts of the data. This helps save internet data and makes it easier for developers.
Core JSON standard (RFC 7159 and RFC 8259)
These are the main rules that define how JSON works. They explain what JSON “grammar” is, what types of data it can hold (like text, numbers, true/false, empty, objects, and lists), and that JSON text should always use UTF-8 coding. These rules make sure JSON works everywhere.
JSON patch and JSON merge patch
These are special ways to update parts of a JSON document instead of sending the whole thing again.
– JSON patch (RFC 6902): This lets you send a list of small changes to make to a JSON document. You can add, remove, change, move, copy, or test parts of the data.
– JSON merge patch (RFC 7396): This is a simpler way to update. You send a JSON document that looks like the parts you want to change, and the system automatically updates the original document. Both methods help make updates faster and use less internet data.
Hypertext application language (HAL)
HAL is a simple rule for embedding links and other pieces of information directly inside JSON responses. This makes APIs “self-describing,” meaning you can easily discover related information and navigate through different parts of the API just by looking at the JSON response.
JSON-LD (Linked data)
JSON-LD helps connect JSON data to the “Linked data” world. It adds special keywords that let computers understand the meaning of the data. This is useful for things like search engine optimisation (SEO) and bringing data together from different sources.
Best ways to use JSON in APIs
When building APIs that use JSON, following some “best practices” helps make them clear, reliable, and easy for others to use.
Design clear and consistent structures
– Easy names: Use names for your API addresses that are clear and describe what they do, usually as plural nouns (like /users instead of /getUser).
– Same style: Pick one way to write names for all your JSON data (like camelCase or snake_case) and stick to it. This makes it easier for everyone to understand and prevents mistakes.
Use proper HTTP signals
– Right status codes: Always use the correct HTTP status codes to show if a request was successful (200 OK), if there was a problem from the user’s end (4xx codes like 404 Not Found), or if there was a problem with the server (5xx codes like 500 Internal Server Error).
– Clear errors: When something goes wrong, include a standard error message in the JSON response (with details like an error code and a message). This helps other programs understand and fix issues automatically.
Check data and manage changes
– Check data: Use a formal “schema” (like a blueprint) to make sure the JSON data always has the right types of information and all the necessary fields. This catches errors early and helps with testing.
– Handle versions: When you make changes to your API, add a version number (like v1 in the address) so old apps still work while new apps can use the updated version.
Make it fast
– Limit data: For lists of items, only send a small part at a time (pagination), and let users filter or sort the data. This prevents sending too much information at once.
– Use caching: Use HTTP “cache headers” to tell computers when they can store a copy of the data. Also, support compressed responses (like gzip) to make data smaller and faster to send.
– Partial responses: Let users ask for only the specific pieces of information they need to reduce the amount of data transferred.
Keep it secure and private
– Always use HTTPS: Use HTTPS to encrypt all data sent between your API and users. This protects sensitive information.
– Check incoming data: Always check and clean any data coming into your API to stop bad attacks.
– No sensitive info: Never show private details like passwords or tokens in your JSON responses.
– Check permissions: Make sure only authorised users can access specific parts of your API.
Write clear instructions
– Good documentation: Keep your API documentation up-to-date. Include examples of requests and responses, explain what each field means, and list all error codes. Tools like Swagger/OpenAPI can even create this documentation automatically, making it super easy for developers.
Support different formats
Respect “Accept” header: Pay attention to what kind of data the user’s program says it wants (using the Accept header, like Accept: application/json). Send the data in the requested format (using the Content-Type header). This allows for supporting other data formats in the future without breaking existing users.
Tools for working with JSON
There are many tools and libraries available to help you work with JSON data, from built-in features to specialised third-party solutions.
Built-in tools (Native parsers)
Most modern web browsers and programming languages already know how to handle JSON.
– For web apps: If you’re building a website, the Fetch API has a special .json() method. This method takes the JSON text from a web response and automatically turns it into a JavaScript object you can use.
– For Python: Python has a built-in json module. It has functions like loads() to turn JSON text into Python dictionaries (like lists of key-value pairs) and dumps() to turn Python data into JSON text. This makes it quick and easy to work with JSON in Python without needing extra software.
Extra tools (Third-party libraries)
For more complex tasks or better performance, you can use specialised libraries:
– Java (Jackson): If you’re using Java, Jackson is a very popular and powerful library for JSON. It can process JSON piece by piece (streaming), connect JSON data to Java objects, and allows for custom ways to convert data.
– Java (Gson): Google’s Gson library is another easy-to-use option for Java. It helps turn Java objects into JSON and vice versa, and can even make the JSON look neat and tidy for reading.
Tools for checking data (Validation)
Making sure your JSON data follows a specific structure is important for stable apps:
– AJV: This is a very fast tool for checking JSON data against a “schema” (a blueprint that defines what the JSON should look like). AJV works in Node.js and web browsers. It helps you find mistakes in your data early on, even during development and testing.
Command-line tools
For quickly looking at or changing JSON data directly in your command line:
– jq: This is a lightweight but powerful tool for processing JSON data. It lets you easily pick out parts of JSON, filter it, change it, and organise it using a simple language. It’s like tools used for text, but specifically for JSON. jq is easy to install and use in scripts.
Tools for testing and fixing APIs
– Postman: This is a complete platform for building and testing APIs. With Postman, you can send requests to your API, see the JSON responses, check if they are correct, and even automate tests. It lets you access parts of the JSON, check if the data matches your rules, and include tests in your development process. Its easy-to-use interface and ability to run multiple tests make it great for trying things out and working with a team.
Where JSON is used in the real world
JSON has become the common language for exchanging data in today’s software. It’s used for everything from how websites talk to each other to storing settings. Because it’s simple, easy to read, and works with many programming languages, it’s perfect for all sorts of applications.
APIs (How programs talk to each other)
JSON is the standard way for most web APIs to send and receive structured information. Almost every big online service, from social media to payment systems, uses JSON in their responses. This makes sure that different programs, no matter what language they’re written in, can understand each other.
Settings and configuration
Many applications use JSON files to store their settings. This is because JSON is easy for both people and computers to read. For example, in Node.js projects, package.json files define project details and rules. This makes it simpler to set up and run programs and helps avoid errors.
NoSQL databases
Databases like MongoDB and CouchDB store and search for data in formats similar to JSON. This means that applications can work directly with complex, nested information without needing extra layers to translate it. This speeds up development and makes it easier to change how data is organised over time.
Single-page and mobile apps
Modern websites and mobile apps (like those built with React or Angular) use JSON APIs to show changing information without reloading the whole page. Getting JSON data quickly helps these apps feel fast and responsive, especially on mobile phones where internet speed can vary.
Microservices and IoT (Internet of things)
– Microservices: In systems made of many small, independent services, these services talk to each other using JSON messages. This makes it easier to define what each service does and to update them without affecting others.
– IoT devices: Devices that connect to the internet (like smart home sensors) often send their data and commands using JSON. This makes it easy for them to share information and connect with cloud platforms.
Logging and analytics (Keeping records and analysing data)
Many backend systems and cloud services store their activity logs in JSON format. Tools like Elasticsearch, Logstash, and Kibana (known as the ELK stack) can read these JSON logs. This allows for searching, filtering, and visualising events in real-time. This practice helps developers understand what’s happening in their systems and fix problems faster, because the JSON logs keep all the important details in a standard way.
Sportmonks: Your go-to for sports data in JSON
Sportmonks offers a set of data services (called REST APIs) for various sports. We provide everything from live scores and game schedules to betting odds and predictions. All this information comes in a well-organised format called JSON.
Our main product, Football API 3.0, covers over 2,500 football leagues globally. It gives you data on:
– Live scores: Get real-time updates on match events’, goals, cards, and player changes. This data is sent as a list of events with details about teams and players.
– Game details: Find full details about upcoming or past matches, including team lineups and statistics.
– Odds and predictions: Access betting odds before and during games, as well as predictions on things like who will win or the final score.
– Custom responses: You can choose exactly what information you want in your JSON responses. This helps you get only what you need and keeps the data small and fast.
Sportmonks also has a Cricket API that gives you:
– Live cricket data: Get live scores, detailed scoreboards (with batting and bowling info), team lineups, and ball-by-ball details. All this comes as JSON data.
– Clear structure: The data is always organised in a consistent JSON way, making it easy to understand and use.
Tools for developers
Sportmonks provides many helpful tools to make it easy for developers to use their data:
– Example files: You can download sample JSON files to see exactly how their data is structured. This helps you plan your projects before writing any code.
– Postman collections: They offer ready-to-use collections for both their Football and Cricket APIs that you can import into Postman. This makes it super simple to explore the data and see live JSON responses.
– Quick start guides: They have step-by-step guides that show you how to get your API key, make your first JSON request, and work with the responses in different programming languages like JavaScript and Python
Use JSON the smart way with Sportmonks
From clean data formats to flexible API design, JSON makes it easy to build fast, reliable apps. Sportmonks uses JSON across all our sports APIs, so you can access real-time scores, stats, and predictions in a format that’s simple to work with and easy to scale.
Start your 14-day free trial and explore how JSON and Sportmonks work together to power smarter sports platforms.
Faqs about JSON response
