json_response

Description:

json response

A most easily usable JSON response wrapper library in Dart!










1. About

1.1. Motivation
1.2. Introduction

1.2.1. Install Library
1.2.2. Import It
1.2.3. Use JsonResponse


1.3. Details

1.3.1. Json

1.3.1.1. Create Instance
1.3.1.2. Get Value
1.3.1.3. Get Multiple Values
1.3.1.4. Get Child JSON
1.3.1.5. Get JSON Array
1.3.1.6. Iteration


1.3.2. JsonArray

1.3.2.1. Create Instance
1.3.2.2. Get JSON
1.3.2.3. Get Nested JSON Array
1.3.2.4. Iteration
1.3.2.5. Flatten A Nested JSON Array




1.4. License
1.5. More Information




1. About #
JsonResponse is an open-sourced Dart library.
With JsonResponse, you can easily and safely handle JSON response on your application.
This library was created with the goal of making JSON response easier, more intuitive, and safer to use in the Dart language.
1.1. Motivation #
For example, as a result of the communication process with the Web API, JSON is returned from the http package and you have ever written the following process when the JSON is set to Response, right?
void main() async {
final response = await http.get(Uri.parse('something'));
final json = jsonDecode(response.body);
print(json['key'] ?? '');
}
copied to clipboard
The above process is not only redundant, but also unsafe from an implementation standpoint, as it requires writing a process for when the value associated with the key does not exist. It becomes even more complicated in the case of a list structure with multiple JSONs. With JsonResponse, the above implementation is no longer necessary!
In addition to JsonResponse, various other JSON-related libraries have been developed, and there are many interesting techniques that use annotations and type inference. However, I feel that those libraries are just complicating a simple problem with too many implementations and configuration files just to process the response returned from the API.
Therefore, JsonResponse does not require any tricky annotations or new configuration files. This library can be used in the same sense as the well-worn JSONObject in Java. It is a horizontal thinking of a dead technology, but it is the easiest and safest algorithm when dealing with JSON response.
1.2. Introduction #
1.2.1. Install Library #
With Dart:
dart pub add json_response
copied to clipboard
With Flutter:
flutter pub add json_response
copied to clipboard
1.2.2. Import It #
import 'package:json_response/json_response.dart';
copied to clipboard
1.2.3. Use JsonResponse #
import 'package:http/http.dart';
import 'package:json_response/json_response.dart';

void main() {
final jsonResponse = Response(
'{"key1": "value", "key2": 1, "key3": true, "key4": {"nested_key1": "nested_value"}}',
200,
);

final jsonArrayResponse = Response(
'''[
{"key1": "value", "key2": 1, "key3": true},
{"key1": "value", "key2": 1, "key3": true},
{"key1": "value", "key2": 1, "key3": true}
]
''',
200,
);

// Json represents a single JSON structure,
// and the JsonArray class represents a multiple JSON structure.
//
// Instantiation of either class is very simple,
// just pass the Response class returned when HTTP communication is
// performed with the http package.
final json = Json.from(response: jsonResponse);
final jsonArray = JsonArray.from(response: jsonArrayResponse);

// Intuitively and safely retrieve data from dedicated methods
// that correspond to data types.
print(json.getString(key: 'key1'));
print(json.getInt(key: 'key2'));
print(json.getBool(key: 'key3'));

// You can also easily retrieve JSON that is nested within JSON.
print(json.get(key: 'key4'));
// You can get this json as a map format.
print(json.toMap());

// The forEach method makes it easy to handle repetitive processes.
jsonArray.forEach((json) {
print(json);
});

// If you are iterating and want the current index as well,
// the enumerate method is useful.
jsonArray.enumerate((index, json) {
print(index);
print(json);
});

// JSON can be retrieved by specifying a specific index,
// but be aware that an exception will be thrown
// if a non-existent index number is specified.
print(jsonArray.get(index: 0));

// If you don't like the structure of several nested lists,
// you can use the flatten method to make the nested structure flat.
// This method returns a new flattened JsonArray.
print(jsonArray.flatten());
}
copied to clipboard
1.3. Details #
1.3.1. Json #
The Json class represents a single JSON structure like below.
{
"key1": "string_value",
"key2": 0,
"key3": 0.0,
"key4": true,
"key5": {
"nested_key1": "string_value"
},
"key6": [
{
"nested_key2": "string_value",
"nested_key3": 1
},
{
"nested_key2": "string_value",
"nested_key3": 1
}
],
"key7": ["value1", "value2"]
}
copied to clipboard
Also, the Json class can automatically detect and convert the following XML format responses into JSON format inside the from constructor. It uses a third party library xml2json to perform this automatic XML to JSON conversion.
<?xml version="1.0" encoding="UTF-8"?>
<records>
<record>
<key>1</key>
<value>1</value>
</record>
<record>
<key>2</key>
<value>2</value>
</record>
</records>
copied to clipboard

Note
When xml2json converts XML to JSON, it uses the Parker method.

1.3.1.1. Create Instance
Json class provides 2 patterns for creating instances.



Constructor




from({required Response response})


empty()



The from constructor takes the Response object returned from the http package as an argument and safely parses the JSON string contained in the response. JSON strings will be parsed in UTF-8 format.
If you need an empty Json, you can get an empty Json object from the empty constructor instead of null.
1.3.1.2. Get Value
The Json class provides safe and convenient ways to retrieve values set in JSON.



Method




getString({required String key, String defaultValue = ''})


getInt({required String key, String defaultValue = -1})


getDouble({required String key, String defaultValue = -1.0})


getBool({required String key, String defaultValue = false})



By using the above methods, you can safely retrieve values with guaranteed types.
If the specified key does not exist or the value is null, the default value will be returned beforehand, but if you want to specify an arbitrary default value, set the defaultValue for each method.
1.3.1.3. Get Multiple Values
JSON may have an array of values associated with the keys, and the Json class provides features for retrieving all the values in such an array at once in a list format.
If there is no value associated with the key, an empty list will be returned.



Method




getStringValues({required String key})


getIntValues({required String key})


getDoubleValues({required String key})


getBoolValues({required String key})



1.3.1.4. Get Child JSON
JSON may be set to the child's JSON as the value associated with the key, and the Json class provides a safe and easy way to retrieve the nested JSON associated with a key.
If there is no value associated with the key, an empty Json will be returned.



Method




get({required String key})



1.3.1.5. Get JSON Array
JSON may be set to an array with multiple JSON as the value associated with the key, and the Json class provides a safe and easy way to retrieve the nested JSON Array associated with a key.
If there is no value associated with the key, an empty JsonArray will be returned.



Method




getArray({required String key})



1.3.1.6. Iteration
The Json class provides convenient features for iterating over JSON objects.



Property / Method




keySet


forEach(void action(String key, dynamic value))



1.3.2. JsonArray #
The JsonArray class represents a multiple JSON structure like below.
[
{
"nested_key2": "string_value",
"nested_key3": 1
},
{
"nested_key2": "string_value",
"nested_key3": 1
}
]
copied to clipboard
1.3.2.1. Create Instance
JsonArray class provides 2 patterns for creating instances.



Constructor




from({required Response response})


empty()



The from constructor takes the Response object returned from the http package as an argument and safely parses the JSON string contained in the response. JSON strings will be parsed in UTF-8 format.
If you need an empty JsonArray, you can get an empty JsonArray object from the empty constructor instead of null.
1.3.2.2. Get JSON
When a JSON Array contains multiple JSON, the get method can be used to get the JSON associated with the index specified in the argument as a Json object.

Note:
Whenever a non-existent index number is specified as an argument, an exception will be raised indicating that the specified index is out of range.




Method




get({required int index})



1.3.2.3. Get Nested JSON Array
When a JSON Array contains nested JSON Array, the getArray method can be used to get the JSON associated with the index specified in the argument as a JsonArray object.

Note:
Whenever a non-existent index number is specified as an argument, an exception will be raised indicating that the specified index is out of range.




Method




getArray({required int index})



1.3.2.4. Iteration
The JsonArray class provides convenient features for iterating over JSON Array objects.



Method




forEach(void action(Json json))


forEachArray(void action(JsonArray jsonArray))


enumerate(void action(int index, Json json))


enumerateArray(void action(int index, JsonArray jsonArray))



You can use the forEach method if the object contained in the JSON Array is a JSON object, and you can use the forEachArray method if it is a nested JSON Array.
If you also need the index number in the iteration process, you can use enumerate or enumerateArray methods.
1.3.2.5. Flatten A Nested JSON Array
The JSON Array may have multiple nested JSON Arrays. And if you don't like the nested structure of that JSON Array, you can use the flatten method to flatten the nested structure.



Method




flatten()



1.4. License #
Copyright (c) 2021, Kato Shinya. All rights reserved.
Use of this source code is governed by a
BSD-style license that can be found in the LICENSE file.
copied to clipboard
1.5. More Information #
JsonResponse was designed and implemented by Kato Shinya.

Creator Profile
License
API Document
Release Note
Bug Report