Poor JSON response structure
simpleshadow opened this issue · comments
Really dig what you've done @meetDeveloper! Was not aware that Google is using Oxford Dictionaries behind the scenes.
While I really dig the API, the current structure of the API responses makes it very unusable (at least in my JavaScript web-based client). Having values as keys is non-standard and iterating over them is a nightmare. For example, the meaning property should be an array and contain a standard object response with partOfSpeech (e.g. { "partOfSpeech": "noun", ... }).
I'd suggest a response that takes cues from the JSON:API spec.
Here's an example of the suggested improvement to the current structure:
{
"word": "work",
"phonetic": [
"wəːk"
],
"meanings": [{
"partOfSpeech": "noun",
"definitions": [
{
"definition": "activity involving mental or physical effort done in order to achieve a purpose or result.",
"example": "he was tired after a day's work in the fields",
"synonyms": [
"labour",
"toil",
"exertion",
"effort",
"slog",
"drudgery",
"the sweat of one's brow"
]
},
{
"definition": "a task or tasks to be undertaken.",
"example": "they made sure the work was progressing smoothly",
"synonyms": [
"tasks",
"jobs",
"duties",
"assignments",
"commissions",
"projects"
]
}
]
}, {
"partOfSpeech": "verb",
"definitions": [
{
"definition": "be engaged in physical or mental activity in order to achieve a result; do work.",
"example": "an engineer who was working on a design for a more efficient wing",
"synonyms": [
"toil",
"labour",
"exert oneself",
"slave (away)",
"plod away"
]
},
{
"definition": "(of a machine or system) function, especially properly or effectively.",
"example": "his phone doesn't work unless he goes to a high point",
"synonyms": [
"function",
"go",
"run",
"operate",
"perform"
]
}
]
}]
}Regrettably, I'm going to use the Oxford Dictionaries API.
@simpleshadow I will look into this, this is my first API, so I did not knew about such things, I will look into it, and I will make changes, because this would be a breaking change, probably, I will ask you to pass version in query param, and based on version show either this structure or old one.
Proposed JSON structure really is more logical, in Turkish, for example, I get 'ünlem' as key in json sometimes and it is not practical to have to iterate trough to be able to access values instead of accessing directly by a known and fixed key.
But as you proposed, it would be nice if current version would keep same structure and the new one would be only for new version of API because it is breaking change.
Some of the "meaning" types that I found:
determiner
abbreviation
noun
verb
adjective
preposition
adverb
preposition & adverb
exclamation
predeterminer, determiner, & pronoun
conjunction
crossReference
transitive verb
determiner & pronoun
pronoun
crossReference
auxiliary verb
preposition, conjunction, & adverb
proper noun
cardinal number
modal verb
plural noun
conjunction & adverb
determiner, pronoun, & adjective
ordinal number
adverb & adjective
adjective & pronoun
preposition & conjunction
determiner, predeterminer, & pronoun
adjective & determiner
conjunction & preposition
relative pronoun & determiner
interrogative adverb
interrogative pronoun & determiner
possessive determiner & pronoun
@simpleshadow @kovinet I have implemented version 1 of api to have this structure, currently I have not implemented for english language, for other languages you can access the version by sending v=1 in query params, can you use it and tell me if that is what you were looking to?
I am also experiencing same problem. The meanings data in JSON response is hard to iterate over. Please make meanings return JSONObjects instead of JSONArrays then the problem would be solved.
@hexdecimal16 I will implement that feature this weekend.
@meetDeveloper Thanks...
@meetDeveloper hey man did you looked it?
Yeah will push fix today or by tomorrow at most.
@hexdecimal16 I have done it, you can change v1 to v2 and it will work. Example: https://api.dictionaryapi.dev/api/v2/entries/en/hello
Sorry for the delay, life got me.
@simpleshadow Can you verify once this is how you wanted?
@meetDeveloper Yah now it's fine. Thanks!