Generic JSON API source

[ifl0w]

I am thinking of a generic JSON API source since there are some requests for relatively simple JSON APIs (e.g.: NASA and Bing) and I do not think that adding all those little sources would result in a good user experience.

The Source would consist out of a base URL where you have to provide the API URL you want to request with all query parameters you need. This could look like this: https://api.nasa.gov/planetary/apod?api_key=YOUR_KEY

The extension would just send a GET request to the given URL and recieve something like this:

{
  "copyright": "Petr Hor\u00e1lek", 
  "date": "2017-08-10", 
  "explanation": "This weekend, [...].", 
  "hdurl": "https://apod.nasa.gov/apod/image/1708/2016_08_06_Perseids_1310pxHoralek.jpg", 
  "media_type": "image", 
  "service_version": "v1", 
  "title": "Night of the Perseids", 
  "url": "https://apod.nasa.gov/apod/image/1708/2016_08_06_Perseids_1310pxHoralek.jpg"
}

The second element of the source settings would be some kind of select expression comparable to a really simple XPATH for JSON. I already found https://github.com/json-path/JsonPath but that supports the same features as XPATH and thus does not support random selection of an array entry. Therefore I'd suggest a really simple select expression syntax that could look like this in the case of the given response: $.hdurl or simply hdurl

If the response is more complicated and would look something like this:

{
"someKey": [
  {
     "someOtherKey": "content",
     "quality": ["https://example.org/HD1.png", "https://example.org/SD1.png"]
  },
  {
     "someOtherKey": "content",
     "quality": ["https://example.org/HD2.png", "https://example.org/SD2.png"]
  },
  ... more items ...
]
}

The select query could look like: $.someKey[@random].quality[0] or someKey[@random].quality[0]

The query could also look like this: someKey.@random.quality.1 This would be easily parsable because all parts that can be converted to an integer would be interpreted as array index and the special keyword @random would select a random index. The problem would be a JSON response that contains a key that is called @random or "1". Therefore I'd favor the first expression syntax.

This could be used by advanced users to support a wide variety of APIs. Of course the drawback is that this would only be usable for advanced/expert users who know the response of the API they want to use and the user would be responsible to provide a correct select expression that returns a valid image URL. Otherwise the background would be set to the default gnome background color that is most likely blue because the gnome-shell would not be able to open the image.

[ifl0w]

This would also support pexels.com.

[Linuturk]

I'm in favor of this as well, using the @random method. There's potential here for providing a series of preset URL and XPATH options for known endpoints like Bing and NASA as part of this Generic API Option. A drop down with a series of endpoints that we know are good, plus the option to edit and override those defaults.

[ifl0w]

So you'd choose the key.@random instead of key[@random] although it could potentially result in bugs? I'd definitely favor key[@random] I think.
But the query syntax is probably not the most important thing. ^^

We should probably add a wiki page with working examples that can be used by novice users when I really implement this source adapter.

[Linuturk]

key[@random] is what I meant.

Building in a drop down with the already working examples, that then fill out the forms with those examples, would be better than documentation in a wiki.

[ifl0w]

Hm that would be a great Idea!

The dropdown could also be filled with examples that are fetched from the github wiki. So that updating the github wiki would update the sourceAdapter for all users.

[ifl0w]

This is basically implemented and merged into develop. I also added some examples in the wiki: https://github.com/ifl0w/RandomWallpaperGnome3/wiki/Generic-JSON-Source