Handle data format changes in PMS v1.3.x

[phillipj]

@benheller from Plex has been kind enough to reach out about breaking changes in the JSON responses from PMS. In PMS v1.3.x there has was introduced some breaking changes in the PMS responses, which I've been told was an effort to prettify, and make the JSON api a supported feature of PMS.

Quoting @benheller:

A pre-1.3.x response might have looked like this:

{
  "_elementType": "MediaContainer",
  "_children": [
    {
      "_elementType": "Hub",
      "size": 0,
      "_children": []
    }
  ]
}

The same response would now be:

{
  "MediaContainer": {
    "size": 12,
    "Hub": []
  }
}

In MOST cases, you can take the _elementType, move it to a top level key (e.g. MediaContainer), and replace _children with its own _elementType (e.g. Hub). That said, the 1.3.0 api changes were inconsistent in places, and on the current release you'll see some keys that do not match the previously reported _elementType properties.

In order to maintain compatibility with both pre- and post-1.3.x versions, the library will need to handle both cases. It may be wise to prioritize XML rather than JSON, which gives you full control over the parsing format via xml2js, so that ALL responses will mimic the "old" style JSON. If a consumer of the library wishes to only support PMS 1.3.x and greater, perhaps you can introduce an option to enable prettified responses?

Initially I agree with Ben on handling both pre / post v1.3.x in this package, so that developers and users of plex-api wouldn't have think about which PMS version they're targeting.

Any thoughts are more than welcome here!

For full disclosure, I cannot work on this for at least or week or two, so any help would be more than welcome.

[ajdexter]

Any updates on this issue?? Understanding your previous disclaimer and that I don't have the skills to lend a hand.

[phillipj]

@ajdexter afraid there's no updates from me at least...

Any thoughts on how you'd expect this to function? As mentioned in the previous comment, it looks like there's two options:

1. Add an option to this package, letting users enabling prettified responses
2. Make this package auto-detect format from the PMS server and possibly transform, ensuring users get one format in the response

The latter might end up putting a lot of complexity into this package, which I've been trying to avoid as much as possible, but that may be worth it if the end-users really expect it.

[hyperlink]

Auto-detect and transform the result would be ideal because that means users won't have to change their code at all. 🥇

[phillipj]

Sure sounds wonderful for the package users 😄

Which format do we want to transform to?

1. old not so pretty format

{
  "_elementType": "MediaContainer",
  "_children": [
    {
      "_elementType": "Hub",
      "size": 0,
      "_children": []
    }
  ]
}

2. new prettified format

{
  "MediaContainer": {
    "size": 12,
    "Hub": []
  }
}

My five cents would go to the prettified format, as it's more JSON-like and to the point vs the old format which looks like XML represented as JSON.

[LanderN]

One vote for the prettified format as it is indeed more JSON and thus easier to work with in JavaScript

[hyperlink]

Not seeing more data with the prettier format. Perhaps a bit more normalized but it looks like the same data structured differently. Either way it will be a breaking change if this module choose to adopt it as dependents will need to update their code. To sum up issues with adopting the new format:

• Module code will need to be rewritten using the new prettier format
• Need to create a converter (convert old format to new format)
• Major version update
• Dependents now forced to update their code to new format to get working state

Keeping the old format:

• Minimal changes to module just add converter to response handler
• Need to create a converter
• Minor or patch update
• Dependents don't need to update their code
• Format still not considered "pretty"

So I lean towards keeping the old format. But ultimately it's up to @phillipj.

BTW I wrote some transform functions last night and I'm hoping to get a branch pushed soon.

[benheller]

Hi all, Plex guy here. Moving forward, you're likely to see more support for the prettified JSON responses. The "old" JSON implementation is largely considered to be unofficial/broken (and I believe actually returns invalid JSON in places). The most robust solution would be to provide an option in the library for responseFormat. It could default to xml, which would make the request using Content-Type: text/xml, run it through an XML > JSON parser, and output something mostly identical to the "old" JSON. The other option could be json, which would make the request using Content-Type: application/json and return the new "prettified" JSON directly. Apps that want to support all PMS versions can use the default XML, and apps that want to support 1.3.x and up can use the json option.

For our internal apps that use node-plex-api we have a :sad_panda: wrapper called getChildren() that looks for child nodes using _children or an array of possible keys (e.g. ['Metadata', 'Directory']). This lets the app be somewhat agnostic to the response format, but it's not ideal. I'd much prefer to get the XML response from the PMS and parse it consistently for all PMS versions (e.g. the xml responseFormat option mentioned above).

[phillipj]

I obviously haven't been able to prioritise this, which I btw feel really bad about since I acknowledge the fact that folks out there are really bother by this bug.

Until I actually do find the time to work on this, I have just published v5.1.0 of plex-api with a backdoor allowing anyone to decide how responses should be parsed. I don't see this as an ideally fix, but it at least makes it a lot simpler for anyone to give it a shot implementing a parser that handles the new PMS v1.3 format.

EDIT:

Have a look at this commit to see how a rather simple response parser can be provided: 76539c8.

I haven't upgrade my Plex Server yet, but looking at response.headers that is provided to a response parser, one might have a chance of identifying newer formats by looking at the x-plex-protocol header which I see as 1.0 on a pre v1.3 Plex Server. Would be nice if someone with an updated server can confirm that header has changed with the new format.

[hyperlink]

The header hasn't changed still 1.0.

[phillipj]

😤 -- thanks for reporting though!

…

On Mon, 17 Apr 2017 at 15:55, Xiaoxin Lu ***@***.***> wrote: The header hasn't changed still 1.0. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#75 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABLLE9RXJwkPB-m1JfzRLVPmA6DRyMqVks5rw29ugaJpZM4LDTBr> .