I need to pass data in a python back-end to a front end through an api call, using a json format. In the python back end, the data is in a dictionary structure, which I can easily and directly convert to a json. But should I?
My front-end developer believes the answer is no, for reasons related to best practice.
But I challenge that:
Is the best to structure a json as it is in python, or should it rather be converted to some other form, such as several arrays (as would be necessary in my example case below)?
Or, differently put:
What should be the governing principles related to collections/dicts/maps/arrays for interfacing information through jsons?
I've done some googling for an answer, but I've not come across much that addresses this directly. Links would be appreciated.
(Note about the example below: of course if the data is written to a database, it would probably make most sense for the front-end to access the database directly, but let's assume this is not the case)
Example:
In the back end there is a collection of objects called pets:
each item in the collection has a unique pet_id, some non-optional properties, e.g. name and date_of_birth, some optional properties registration_certificate_nr, adopted_from_kennel, some lists like siblings and children and some objects like medication.
Assuming that the front end needs all of this info at some point, it could be
{
"pets": {
"17-01-24-01": {
"name": "Buster",
"date_of_birth": "04/01/2017",
"registration_certificate_nr": "AAD-1123-1432"
},
"17-03-04-01": {
"name": "Hooch",
"date_of_birth": "05/02/2015",
"adopted_from_kennel": "Pretoria Shire",
"children": [
"17-05-01-01",
"17-05-01-02",
"17-05-01-03"
]
},
"17-05-01-01": {
"name": "Snappy",
"date_of_birth": "17-05-01",
"siblings": [
"17-05-01-02",
"17-05-01-03"
]
},
"17-05-01-02": {
"name": "Gizmo",
"date_of_birth": "17-05-01",
"siblings": [
"17-05-01-01",
"17-05-01-03"
]
},
"17-05-01-03": {
"name": "Toothless",
"date_of_birth": "17-05-01",
"siblings": [
"17-05-01-01",
"17-05-01-03"
],
"medication": [
{
"name": "anti-worm",
"code": "aw445",
"dosage": "1 pill per day"
},
{
"name": "disinfectant",
"code": "pdi-2",
"dosage": "as required"
}
]
}
}
}
JSON formatting is a somewhat subjective matter, and related disagreements are usually best settled between colleagues.
That being said, there are some potentially valid criticisms to be made against the JSON format in the question, especially if we are trying to create a consistent, RESTful API.
The 2 pain points that stand out:
A map collection is represented in JSON, which isn't really JSON standard compliant, or particularly RESTful.
None of the pet objects have an id defined. There is a pet_id mentioned in the question, but it seems to be maintained separately from the pet object itself. If a value is accessed in the pets map in the question, a user of the API would have to manually add the pet_id to the provided pet object in order to have the id available further down the line, when the full JSON may no longer be available.
The closest things we have to guiding standards in this situation is the REST architectural style and the JSON standard.
We can start by looking at the JSON standard. Here is a quote from the JSON wiki:
JavaScript syntax defines several native data types that are not included in the JSON standard: Map, Set, Date, Error, Regular Expression, Function, Promise, and undefined.
The key takeaway here is that JSON is not meant to represent the map data type. Python dictionaries are a map implementation, so directly serializing a dictionary to JSON with the intent to represent a map-like collection goes against the intended use of JSON.
For an individual object like a pet, the JSON object is appropriate, but for collections there is one option: the JSON array. There is a usage example with the JSON array further down in this answer.
There may be edge cases where deviating from the standard makes sense, but I don't see a reason in this scenario.
There are also some shortcomings in the JSON format from a RESTful design perspective. RESTful API design is nice because it encourages one to keep things simple and consistent. It also happens to be a de facto industry standard.
In a RESTful HTTP API, this is how fetching a single pet resource should look:
Request: GET /api/pets/17-01-24-01
Response: 200 {
"id": "17-01-24-01",
"name": "Buster",
"date_of_birth": "04/01/2017",
"registration_certificate_nr": "AAD-1123-1432"
}
The response is a completely defined resource with an explicitly defined id. It is also the simplest complete JSON representation of a pet.
Next, we define what fetching multiple pet resources looks like, assuming only 2 pets are defined:
Request: GET /api/pets
Response: 200 [
{
"id": "17-01-24-01",
"name": "Buster",
"date_of_birth": "04/01/2017",
"registration_certificate_nr": "AAD-1123-1432"
},
{
"id": "17-03-04-01",
"name": "Hooch",
"date_of_birth": "05/02/2015",
"adopted_from_kennel": "Pretoria Shire",
"children": [
"17-05-01-01",
"17-05-01-02",
"17-05-01-03"
]
}
]
The above response format is the most straight forward way to pluralize the single resource response format, thus keeping the API as simple and consistent as possible. (for the sake of brevity, I only used 2 of the sample resources from the question). Once again, the ids are explicitly defined, and belong to their respective pet objects.
Nothing is gained from adding map keys to the above format.
Proponents of the JSON format in the question may suggest to just add the id field into each pet object in order to work around pain point 2, but that would raise the question of repeating data within the response. Why does the id need to be both inside and outside the object? Surely it should only be on the inside? After eliminating the redundant data, the result will look like the response above.
That is the REST argument. There are use cases where REST doesn't really work, but this is far from that.
PS. Front ends should never access databases directly. The API is responsible for writing to and reading from whatever data persistence infrastructure is used. In a lot of bigger real world systems, there is even an additional BFF layer between the front end and the API(s), separating the front end and the DB even further.
Related
Is there is any function available in python to convert the given json input into HL7 FHIR format. By passing the Liquid Template (Shopify) and the input source data.
Not that I am aware of, but I stand corrected; You will most likely have to create your own.
See example of someone who had a near similar problem: https://forums.librehealth.io/t/project-rest-json-to-fhir-json-mapping-implementation/1765/14
Thinking that you are looking for something like fhir.resources library, where you can provide some dictionary with data to some kind of object that can be serialized.
from fhir.resources.organization import Organization
from fhir.resources.address import Address
data = {
"id": "f001",
"active": True,
"name": "Acme Corporation",
"address": [{"country": "Switzerland"}]
}
org = Organization(**data)
org.resource_type == "Organization"
P.S. But don't quite follow why you mentioned Liquid Templates.
I have a JSON Schema file like this one, which contains a couple of intentional bugs:
{
"$schema": "http://json-schema.org/schema#",
"type": "object",
"description": "MWE for JSON Schema Validation",
"properties": {
"valid_prop": {
"type": ["string", "number"],
"description": "This can be either a string or a number."
},
"invalid_prop": {
// NOTE: "type:" here should have been "type" (without the colon)
"type:": ["string", "null"],
"description": "Note the extra colon in the name of the type property above"
}
},
// NOTE: Reference to a non-existent property
"required": ["valid_prop", "nonexistent_prop"]
}
I'd like to write a Python script (or, even better, install a CLI with PiP) that can find those bugs.
I've seen this answer, which suggests doing the following (modified for my use case):
import json
from jsonschema import Draft4Validator
with open('./my-schema.json') as schemaf:
schema = json.loads('\n'.join(schemaf.readlines()))
Draft4Validator.check_schema(my_schema)
print("OK!") # on invalid schema we don't get here
but the above script doesn't detect either of the errors in the schema file. I would have suspected it to detect at least the extra colon in the "type:" property.
Am I using the library incorrectly? How do I write a validation script that detects this error?
You say the schema is invalid, but that isn't the case with the example you've provided.
Unknown keywords are ignored. This is to allow for extensions to be created. If unknown keywords were prevented, we wouldn't have the ecosystem of extensions that various people and groups have created, like form generation.
You say that the value in required is a "Reference to a non-existent property". The required keyword has no link to the properties keyword.
required determins which keys an object must have.
properties determines how a subschema should be applied to values in an object.
There's no need for values in required to also be included in properties. In fact it's common that they do not when building complex modular schemas.
In terms of validating if a schema is valid, you can use the JSON Schema meta schema.
In terms of checking for additional things that you consider non desireable, that's down to you, given the examples you've provided are valid.
Some libraries may provide a sanity check, but such is unlikely to pick up on the examples you've provided, as they aren't errors.
I get data in JSON from an API and it may be that the received data is not complete (= some fields are missing). I am not sure either that the structure of the data follows JSON standards.
The solution for the second problem is simple: I will try: to decode the JSON and act accordingly on ValueError and TypeError exceptions.
For the first problem, my solution would also be to
d = {'a': 1}
try:
d['a']
d['b']
d['x']['shouldbethere']
except KeyError:
(...)
that is to list all the keys I need to have in the dict created from a successful JSON conversion.
This made me think that there may be a method to declare the expected keys (and possibly values types) and match the retrieved JSON against it, an unsuccessful match raising a specific exception?
Standard way to validate JSON structure is to use JSON Schema.
Basic characteristics (quoted from official webpage) are:
JSON Schema:
describes your existing data format
clear, human- and machine-readable documentation
complete structural validation, useful for
automated testing
validating client-submitted data
There is no built-in package to validate JSON object against schema, although you may use jsonschema from pypi.
Sample usage (paraphrased from official docs) may be:
import jsonschema
schema = {
"type": "object",
"properties": {
"price": {"type": "number"},
"name": {"type": "string"},
},
}
jsonschema.validate({"name": "Eggs", "price": 34.99}, schema)
# No exception from line above - document is valid
jsonschema.validate({"name": "Eggs", "price": "Invalid"}, schema)
# ValidationError: 'Invalid' is not of type 'number'
JSON parsers aren't terribly easy to use for error correction, so if the data isn't JSON I think it would be very difficult to apply any kind of auto-correction to allow you to parse it, so your solution for the invalid JSON is probably the most reasonable decision.
A function to verify that a dict contains a particular set of keys is relatively easy to implement. I'm not aware of any JSON object methods to perform that test, but given a JSON object j you could check it as follows (it might also be sensible to check that it's a dict, since JSON objects can also be of other types):
def has_all_keys(j, keylist):
return all(key in j for key in keylist)
Using this interactively suggests is might work (in this example I rely on the fact that iteration over a string yields the individual characters, but obviously you will need a real list of string key values).
>>> has_all_keys({}, "abc")
False
>>> has_all_keys({'a':1, 'b':1, 'c':1}, "abc")
True
I'm coding an API library in Python, I always chose json before as the response format but this API provides text and json formats, I'm not asking which one is easier or better, I want to know the advantages and the disadvantages of using both as I only worked with json before.
I thought about using text format, it's very easy to parse but the only thing I thought about was the nested elements, but after checking the example they're separated with underscores _ for example:
name=VALUE
lastname=VALUE
age=VALUE
contact_email=VALUE
contact_phone=VALUE
contact_mobile=VALUE
same json response:
{
"name": "VALUE",
"lastname": "VALUE",
"age": "VALUE",
"contact": {
"email": "VALUE",
"phone": "VALUE",
"mobile": "VALUE"
}
}
So is there any advantages or disadvantages of using text over json or the other way around ?
IMHO the main advantages of json over text would be:
DRY - there are third party libs for json processing which are quite performant
The parsed json ends up being a dict, which you cam refer by keys easily
For the text variant, there is the .ini format, which could offer something aling the lines of structure, although the format you described above is not really designed for nested fields and structures.
I'd also look at who's consuming your API. E.g. if it's a web app, then json is the accepted format. if your consumer is something else which is more comfortable with the text format...
JSON can be easier as you can use the json library.
The return you've shown there can be put into a dictionary with the line:
import json
json.loads(return_string)
Much easier to parse than the text!
I am working on a system to output a JSON file and I use Python to parse the data and display it in a UI (PySide). I now would like to add filtering to that system and I think instead of writing a query system, if there was one out there for JSON (in Python), that would save me a lot of development time. I found this thread:
Is there a query language for JSON?
but that's more for a Web-based system. Any ideas on a Python equivalent?
EDIT [for clarity]:
The format the data that I'll be generating is like this:
{
"Operations": [
{
"OpID": "0",
"type": "callback",
"stringTag1": "foo1",
"stringTag2": "FooMsg",
"Children": [...],
"value": "0.000694053"
},
{
"OpID": "1",
"type": "callback",
"stringTag1": "moo1",
"string2": "MooMsg",
"Children": [...],
"value": "0.000468427"
}
}
Where 'Children' could be nested arrays of the same thing (other operations). The system will be built to allow users to add their own tags as well to the data. My hope was to have a querying system that would allow users to define their own 'filters' as well, hence the question about the querying language. If there was something that would let me do something like "SELECT * WHERE "type" == "callback" and get the requisite operations back, that would be great.
The suggestion of Pync is interesting, I'll give that a look.
I notice this question was asked a few years ago but if someone else find this, here are some newer projects trying to address this same problem:
ObjectPath (for Python and Javascript): http://objectpath.org/
jsonpath (Python reimplementation of the Javascript equivalent): https://pypi.org/project/jsonpath/
yaql: https://yaql.readthedocs.io/en/latest/readme.html
pyjq (Python bindings for jq https://stedolan.github.io/jq/): https://pypi.org/project/pyjq/
JMESPath: https://github.com/jmespath/jmespath.py
I personally went with pyjq because I use jq all the time for data exploration but ObjectPath seems very attractive and not limited to json.
I thought about this a little bit, and I lean towards something less specific such as a "JSON Query Language" and considered something more generic. I remembered from working with C# a bit that they had a somewhat generic querying system called LINQ for handling these sort of querying issues.
It looks as though Python has something similar called Pynq which supports basic querying such as:
filtered_collection = From(some_collection).where("item.property > 10").select_many()
It even appears to have some basic aggregation functions. While not being specific to JSON, I think it's a least a good starting point for querying.
You can also check out PythonQL, a query language extension to Python that handles SQL and JSON queries: pythonql
pyjsonq
https://github.com/s1s1ty/py-jsonq
from pyjsonq import JsonQ
qe = JsonQ('myfile.json')
res = qe.at('products').where('cat', '=', 2).get()
print(res)
"""
[
{
id: 3,
city: 'dhk',
name: 'Redmi 3S Prime',
cat: 2,
price: 12000
},
...
]
I think it's important that the interaction with json is in-memory so that you can still do things manually for complex criteria